initial commit

skills/self-hosting/firebase-to-pocketbase-migration/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: firebase-to-pocketbase-migration
+description: Migrate a Firebase web app to self-hosted PocketBase — build a Firebase-compatible adapter, swap imports, and deploy with same-origin nginx proxy.
+triggers:
+  - "migrate from Firebase"
+  - "replace Firebase with PocketBase"
+  - "Firebase to PocketBase"
+  - "remove Firebase dependency"
+  - "self-host instead of Firebase"
+---
+
+# Firebase → PocketBase Migration
+
+Replace Firebase (Auth + Firestore) with PocketBase without rewriting the app. Build a thin compatibility adapter, swap one import per file, and deploy behind same-origin nginx so the PocketBase JS SDK works without CORS.
+
+## Strategy: Adapter, Don't Rewrite
+
+Firebase apps import from `firebase.js` (or CDN) and call `signInWithEmailAndPassword(auth, ...)`, `collection(db, 'name')`, `addDoc(ref, data)`, `getDocs(query(...))`, etc. PocketBase has a different API surface.
+
+**The adapter** (`pocketbase.js`) exports `auth` and `db` objects that mirror the Firebase surface, backed by PocketBase under the hood. All 13+ app files keep their existing `collection()`, `query()`, `where()`, `getDocs()`, `addDoc()`, etc. calls unchanged.
+
+## Step 1: Map the Firestore Data Model
+
+Search for all Firestore references:
+
+```bash
+grep -rn "collection(db," *.js shared/*.js
+grep -rn "gstatic.com/firebasejs" *.js shared/*.js
+```
+
+Identify:
+- **Top-level collections** (e.g., `repairOrders`, `appointments`)
+- **Sub-collections** (e.g., `users/{uid}/services`, `users/{uid}/customers`)
+- **Dynamic imports** (`await import("...firebase-firestore.js")`)
+- **Auth functions used** (`signOut`, `onAuthStateChanged`, `updateProfile`, `sendPasswordResetEmail`)
+
+## Step 2: Flatten Sub-Collections
+
+PocketBase has no native sub-collections. Flatten them into top-level collections with a `userId` field:
+
+| Firestore | PocketBase Collection | Key Field |
+|---|---|---|
+| `repairOrders` | `repairOrders` | `userId` |
+| `users/{uid}/services` | `services` | `userId` |
+| `users/{uid}/customers` | `customers` | `userId` |
+| `users/{uid}/settings/{docName}` | `settings` | `userId` + `name` |
+
+The adapter handles the path translation transparently — app code still writes `collection(db, 'users', uid, 'services')`.
+
+## Step 3: Create PocketBase Collections
+
+Use the Admin API to create collections before writing any data. **Create with empty rules first, then PATCH rules after the schema exists** — rules that reference fields fail validation if the field doesn't exist yet.
+
+### v0.22 and earlier (uses `schema` key)
+
+```python
+api("POST", "/api/collections", {
+    "name": "repairOrders", "type": "base",
+    "schema": [{"name": "userId", "type": "text", "required": True}],
+    "listRule": "", "viewRule": "", "createRule": "",
+    "updateRule": "", "deleteRule": ""
+}, token)
+```
+
+### v0.23+ (uses `fields` key)
+
+```python
+api("POST", "/api/collections", {
+    "name": "repairOrders", "type": "base",
+    "fields": [{"name": "userId", "type": "text", "required": True}],
+    "listRule": "", "viewRule": "", "createRule": "",
+    "updateRule": "", "deleteRule": ""
+}, token)
+```
+
+To check your PocketBase version: `docker exec pocketbase /usr/local/bin/pocketbase --version`
+
+### Two-step: schema first, rules second
+
+```python
+# Step 1: Set schema with empty rules
+api("PATCH", f"/api/collections/{col_id}", {
+    "fields": [...all fields including system id field...],
+    "listRule": "", "viewRule": "", "createRule": "",
+    "updateRule": "", "deleteRule": ""
+}, token)
+
+# Step 2: Apply rules now that fields exist
+api("PATCH", f"/api/collections/{col_id}", {
+    "listRule": "userId = @request.auth.id",
+    "viewRule": "userId = @request.auth.id",
+    "createRule": "@request.auth.id != ''",
+    "updateRule": "userId = @request.auth.id",
+    "deleteRule": "userId = @request.auth.id",
+}, token)
+```
+
+**⚠️ You MUST include the system `id` field** (with its existing properties) when PATCHing fields in v0.23+, or the update may be rejected. Fetch the collection first to get the existing field definitions, then merge new fields into them.
+
+### Define ALL fields, not just userId
+
+Firebase/Firestore is schemaless — you can add any field to a document dynamically. PocketBase is **strictly typed** — any field not defined in the collection schema is **silently dropped on write** (HTTP 200 is returned but the data is not stored). You MUST define every field the app writes before any data operations.
+
+Use `references/collection-schema-setup.py` as a template — it defines complete schemas for all common Firebase collection types and handles the two-step schema+rules process.
+
+Create one collection per top-level name: `repairOrders`, `appointments`, `quotes`, `tasks`, `services`, `customers`, `settings`.
+
+## Step 4: Build the Adapter
+
+Use `templates/pocketbase-adapter.js` as a starting point. The adapter handles Auth + Firestore CRUD with PocketBase underneath. Also see `templates/same-origin-nginx.conf` for the nginx config, `references/create-collections.py` for the original collection creation script (v0.22), and **`references/collection-schema-setup.py`** for the complete field schema definitions with v0.23+ two-step process.
+
+**⚠️ Critical compatibility requirements** for `getDoc`, `getDocs`, `addDoc`, and `onSnapshot` are documented in **`references/adapter-firestore-compat-patterns.md`**. Read this before writing or debugging the adapter — the return shapes must match the Firestore SDK exactly or every app file silently breaks.
+
+### Auth surface (Firebase-compatible)
+- `auth.currentUser` → `{ uid, email, displayName }`
+- `auth.onAuthStateChanged(callback)` → fires on change + returns unsubscribe
+- `signInWithEmailAndPassword(auth, email, password)` → PocketBase `authWithPassword()`
+- `createUserWithEmailAndPassword(auth, email, password)` → PocketBase `create()` + `authWithPassword()`
+- `signOut(auth)` → `pb.authStore.clear()`
+- `sendPasswordResetEmail(auth, email)` → PocketBase `requestPasswordReset()`
+- `updateProfile(user, {displayName})` → PocketBase `update()`
+
+### Firestore surface
+- `collection(db, name)` / `collection(db, 'users', uid, 'sub')` — top-level and sub-collection
+- `doc(db, 'col', id)` / `doc(db, 'users', uid, 'settings', name)` — top-level and nested
+- `query(ref, where(field, op, val), orderBy(field, dir))` — compiled to PocketBase filter strings
+- `getDocs(query)` — must return Firestore-compatible **snapshot shape**: `{docs: [...], size: N, empty: bool, forEach(cb)}`. Not a raw array — every consumer calls `.docs.map()`, `.empty`, `.size`, or `.forEach()`.
+- `getDoc(docRef)` → `pb.collection(name).getOne(id)`. **⚠️ Must return `exists` as a function** (`exists: () => true`/`exists: () => false`), not a boolean. Firestore API calls `.exists()` everywhere.
+- `addDoc(ref, data)` → `pb.collection(name).create(data)`. **⚠️ Must inject `userId` from sub-collection ref.** When app code writes `collection(db, 'users', uid, 'services')`, the adapter tracks `_userId` on the ref but `create()` discards it. Always: `if (ref._userId && !data.userId) { data.userId = ref._userId; }` before calling `create()`.
+- `updateDoc(docRef, data)` → `pb.collection(name).update(id, data)`
+- `deleteDoc(docRef)` → `pb.collection(name).delete(id)`
+- `onSnapshot(queryOrDoc, callback)` — **⚠️ Must pass snapshot shape to callback.** A bare `getDocs(query).then(docs => callback({docs}))` is wrong. Wrap in `createQuerySnapshot(docs)` that includes `size`, `empty`, `forEach`. Reference the same helper used by `getDocs`.
+- `serverTimestamp()` → `new Date().toISOString()`
+- `Timestamp` class — wraps Date for `.toDate()` calls on existing timestamp fields
+
+### Query operator mapping
+| Firebase | PocketBase Filter |
+|---|---|
+| `where('field', '==', val)` | `field = "val"` |
+| `where('field', 'in', [a,b])` | `(field ?= "a" \|\| field ?= "b")` |
+| `orderBy('field', 'desc')` | `-field` sort parameter |
+
+### Data conversion
+- **To PB**: Nested objects get `JSON.stringify()`'d. `undefined` values dropped. Dates → ISO strings.
+- **From PB**: ISO strings on known timestamp fields → `Timestamp` objects. JSON strings in object-like fields → parsed back.
+
+## Step 5: Swap All Imports
+
+Replace Firebase CDN imports with the adapter in one sweep:
+
+```bash
+# Static imports
+find . -name "*.js" -exec sed -i 's|from "./firebase.js"|from "./pocketbase.js"|g' {} +
+find . -name "*.js" -exec sed -i 's|from "https://www\.gstatic\.com/firebasejs/[^"]*firebase-auth\.js"|from "./pocketbase.js"|g' {} +
+find . -name "*.js" -exec sed -i 's|from "https://www\.gstatic\.com/firebasejs/[^"]*firebase-firestore\.js"|from "./pocketbase.js"|g' {} +
+
+# Dynamic imports
+find . -name "*.js" -exec sed -i 's|await import("https://www\.gstatic\.com/firebasejs/[^"]*firebase-auth\.js")|await import("./pocketbase.js")|g' {} +
+find . -name "*.js" -exec sed -i 's|await import("https://www\.gstatic\.com/firebasejs/[^"]*firebase-firestore\.js")|await import("./pocketbase.js")|g' {} +
+
+# Also check login.html for inline module scripts
+# Also check any single-quoted import() calls
+```
+
+Verify zero Firebase references remain:
+```bash
+grep -rn 'gstatic.com/firebasejs' *.js shared/*.js *.html
+```
+
+## Step 6: Same-Origin nginx (No CORS)
+
+PocketBase SDK uses `window.location.origin`. Serve the static app AND proxy `/api/` to PocketBase from the same nginx server block:
+
+Use `templates/same-origin-nginx.conf` as the template. Key points:
+- `root /path/to/app;` serves static files
+- `location /api/ { proxy_pass http://127.0.0.1:8091; }` proxies PocketBase
+- `location /_/ { proxy_pass ... }` for admin UI access
+- SPA fallback: `try_files $uri $uri/ /index.html;`
+- WebSocket headers for realtime: `Upgrade`, `Connection`, `proxy_read_timeout 86400`
+
+This avoids CORS entirely — PocketBase calls go to `/api/collections/users/auth-with-password` on the same origin.
+
+## Pitfalls
+
+- **`onAuthStateChanged` must be exported as a standalone function.** Many files import `import { onAuthStateChanged } from "./pocketbase.js"` and call `onAuthStateChanged(auth, callback)`. If you only export it as `auth.onAuthStateChanged` (a method on the auth object), those imports resolve to `undefined` and the auth check silently does nothing — user sees the app without any auth redirect. Always add a standalone wrapper: `function onAuthStateChanged(authRef, callback) { return auth.onAuthStateChanged(callback); }` and export it alongside the other functions.
+- **Settings pages need `updatePassword`, `reauthenticateWithCredential`, `EmailAuthProvider`.** If the app has a profile/settings page, these Firebase Auth functions are imported. PocketBase equivalents: `updatePassword` calls `pb.collection('users').update(uid, {password, passwordConfirm})`. `reauthenticateWithCredential` re-runs `authWithPassword`. `EmailAuthProvider.credential(email, pass)` returns a credential object for re-auth.
+- **`setDoc`, `limit`, `onSnapshot` are commonly imported but easy to miss.** `setDoc` = upsert (try `update`, fallback to `create` with explicit ID). `limit(n)` returns a constraint object used in query building. `onSnapshot` can be a simple polling one-shot that calls `getDocs`/`getDoc` then fires the callback — most apps only need the initial snapshot, not real-time.
+- **`limit` must be handled in `getDocs`.** When a query has a limit constraint, use `pb.collection(name).getList(1, limitVal, options)` instead of `getFullList()`. `getFullList` fetches all pages; `getList` respects the pagination cap.
+
+- **PocketBase SDK auto-cancellation (`requestKey: null`).** The PocketBase JS SDK auto-cancels in-flight requests that share the same `requestKey` (derived from method + URL by default). All `create` calls to the same collection share a key, so a double-submit cancels the first request with "auto-cancelled" error. Fix: pass `{ requestKey: null }` to ALL mutating calls — `pb.collection(name).create(data, { requestKey: null })`, `pb.collection(name).update(id, data, { requestKey: null })`, and the same inside `setDoc`'s upsert paths. Also add a client-side guard: disable the submit button on first click to prevent double submissions.
+- **`index.html` may load `firebase.js` via `<script>` tag.** `<script type="module" src="firebase.js"></script>` needs to become `src="pocketbase.js"`. HTML files are easy to miss when swapping imports in `*.js` files only.
+- **Mount paths must match entrypoint flags** (see `pocketbase-setup` skill). The image uses `--dir=/pb_data --publicDir=/pb_public`.
+- **Docker restart ignores compose changes.** After editing volumes/ports, use `down && up -d`.
+- **Admin `upsert` needs `--dir=/pb_data`** flag when running inside container.
+- **Auth API uses `_superusers`, not `admins`** in PocketBase v0.22+.
+- **Users collection system ID is `_pb_users_auth_`** — use PATCH on that ID, not POST to `/api/collections/users`.
+- **Rules referencing fields fail if created with the collection.** Create with empty rules, then PATCH rules after schema exists.
+- **Dynamic `await import()` calls** are easy to miss — check for both `"..."` and `'...'` quoting.
+- **`login.html` may have inline `<script type="module">`** with Firebase imports — check HTML files too, not just JS.
+- **`sendPasswordResetEmail` and `updateProfile`** aren't in the base adapter — add them if the login page uses them.
+- **Nested objects** get JSON.stringified by the adapter — Firestore stores them natively. This is lossy but reversible for most data shapes.
+- **Timestamp fields** are auto-detected by field name (writeupTime, createdAt, etc.) — add to `TIMESTAMP_FIELDS` Set if the app has differently-named timestamp fields.
+- **Admin auth leaks into app pages.** If the user logged into PocketBase Admin UI (`/_/`) on the same origin, the superuser auth token persists in localStorage. On next visit to the app, `pb.authStore.isValid` returns true and `currentUser` is a superuser — the dashboard loads without login. Fix: in the adapter's `auth.currentUser` getter and `onAuthStateChanged` listener, check `model.collectionName === 'users'`. Return null for `_superusers`. This prevents admin sessions from auto-authenticating the app.
+
+- **Cached user tokens also bypass login.** After fixing the admin auth leak (above), the user may still see the dashboard instead of the login page. This happens because the PocketBase SDK auto-restores **any** valid token from localStorage at initialization — including tokens from a previous `test@...` user login. The adapter's admin filtering only rejects `_superusers`; a valid `users` collection token passes right through. Fix: either (a) instruct the user to clear site data (DevTools → Application → Clear storage, or hard refresh with `Ctrl+Shift+Delete` → clear cache), or (b) add a manual sign-out button that calls `pb.authStore.clear()`. Without one of these, the user is permanently auto-authenticated until the token expires.
+
+- **Dynamic imports in `shared/` resolve to the wrong directory.** After swapping Firebase CDN imports to `./pocketbase.js` in Step 5, files inside `shared/` (like `shared/header-functionality.js`) will have broken paths. `import('./pocketbase.js')` from `shared/` resolves to `shared/pocketbase.js` — but `pocketbase.js` lives in the project **root**. Fix: change to `import('../pocketbase.js')` in all `shared/` files. Also check for stale Firebase paths: `import('../firebase.js')` must become `import('../pocketbase.js')`. Search with: `grep -rn "pocketbase.js\|firebase.js" shared/`.
+
+- **Nginx `Cache-Control: immutable` breaks all JS updates.** Many static-site nginx configs set `expires 30d; add_header Cache-Control "public, immutable"` on JS/CSS files. After swapping to PocketBase, browsers serve stale `${OLD}` JS files forever — even after the fix above. Change to `expires 1h; add_header Cache-Control "public, must-revalidate"` and reload nginx. Also add `?cb=` cache-busting to all redirects as a defense-in-depth measure (see `web-ui-repair` skill, section 2).
+
+- **CSP on index.html silently blocks all inline fixes after migration.** Post-migration inline script guards and onclick handlers may be blocked by a Content Security Policy meta tag that lacks `'unsafe-inline'`. Diagnostic signal: inline fixes work on other pages (no CSP) but fail on index.html. Fix: add `'unsafe-inline'` to script-src. Full pattern in `web-ui-repair` skill, section 13.
+
+- **Direct SQLite field manipulation breaks PocketBase schema validation.** If you modify the `_collections` table's `fields` column directly (instead of via the API), each field object in the JSON array MUST include a unique `id` property (a string like `"text3208210256"` that PocketBase generated at creation time). Without valid `id` properties, PocketBase cannot parse the field definitions and ALL create/update operations fail with a generic `"Failed to create record."` error — regardless of user permissions or data validity.\n\n  **Fix:** Always use `PATCH /api/collections/{id}` via the API to add fields. This generates proper `id` values automatically. Fetch the existing collection first (`GET /api/collections/{id}`), merge new fields into the returned `fields` array, then PATCH back.\n\n- **Define ALL fields before CRUD, not just userId.**** Unlike Firestore (schemaless), PocketBase has a strict typed schema. Creating/updating a record with a field not defined in the collection schema returns **HTTP 200** but the field value is discarded — no error, no warning, just lost data. This is the #1 cause of "everything looks like it works but there's no data." **Define every field the app writes before any CRUD.** See Step 3 for the two-step schema+rules process and the `references/collection-schema-setup.py` template.
+
+- **Import consolidation can accidentally drop non-Firebase imports.** When manually consolidating Firebase CDN imports into `./pocketbase.js`, adjacent non-Firebase imports (like `import { escapeHtml } from './shared/sanitize.js'`) may be deleted. After consolidation, grep each file for undeclared function references: `grep -n "escapeHtml\|showNotification\|formatCurrency" *.js shared/*.js | grep -v "^.*:import"`. If a function is used but not imported, restore the import.
+
+- **Restrictive file permissions break module loading.** When copying migrated files to the deployment directory, files may have owner-only permissions (600). nginx runs as `www-data` and returns HTTP 403 for unreadable files — which causes **silent ES module chain failure** (no console error visible but no handlers attach). Fix: `find . -name "*.js" -exec chmod 644 {} +` after deployment. Verify with `curl -skI https://site.com/key-file.js | head -1` — should return 200, not 403.
+
+- **Settings save/load breaks silently on PocketBase schema mismatch.** If a collection (e.g., `settings`) only has `id`, `userId`, `name` text fields but the app tries to save arbitrary key-value settings directly, PocketBase silently drops unknown fields. Fix: add a `json` field to the collection, wrap data in `{data: {...}, userId, name}`, and use query-based upsert in `setDoc`/`getDoc` (PocketBase v0.23+ requires system IDs ≥ 15 chars). Full pattern in **`references/settings-json-field-pattern.md`**.
+
+## Debugging
+
+See **`references/debugging-migration-bugs.md`** for common bug patterns discovered during migration validation, including:
+
+| Pattern | Symptom | Fix |
+|---|---|---|
+| Dual render path filter mismatch | Completed items stay visible after status change | Sync filter between load-from-DB and re-render-local paths |
+| Silent setTimeout errors | Button click "does nothing", no console error | Try/catch inside the callback, not outside |
+| PocketBase drops undefined fields | API returns 200 but data is missing | Define every field in schema before CRUD |
+| Reference build comparison | "But the Firebase version works!" — same code bug | Use `diff` on identical functions; the Firebase version had the same bug, just unnoticed |