@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/patterns-standards/PHASE_IMPORT_ERROR_DEBUGGING.md

@@ -0,0 +1,271 @@
+# Phase Import Error Debugging - Multi-File Server Crash Investigation
+
+## The Problem
+
+After implementing a multi-file feature phase (Phase 3.4 - Student Activity Timeline), the server crashed with import errors. A previous fix attempt was reverted, leaving the codebase in a broken state. The initial symptom reported was misleading (react-quill CSS import), but the real issues were server-side import errors in newly created files.
+
+### Error Messages
+
+```
+Error: Cannot find module '../middleware/auth.js' imported from authMiddleware
+Error: sql is not a function (from database.js which doesn't export sql)
+Error: node-fetch is not defined (on Node 18+ where native fetch exists)
+```
+
+### Why It Was Hard
+
+1. **Misleading initial symptom** - The handoff mentioned "react-quill CSS import" failure, but the real issues were server-side
+2. **Revert obscured the problem** - A fix commit (054c62f) was reverted, putting broken imports back
+3. **Multiple files affected** - Three different files had three different import errors
+4. **ES Module specifics** - The errors relate to ES Module export/import patterns
+5. **Environment differences** - Local (Node 24) worked, server (Node 18) failed
+
+### Impact
+
+- Server would not start
+- All Phase 3.4 features unavailable
+- Required git revert which lost valid fixes
+- Blocked deployment pipeline
+
+---
+
+## The Solution
+
+### Root Cause
+
+Phase 3.4 created several server files with **incorrect assumptions about exports**:
+
+| File | Wrong Import | Correct Import | Why Wrong |
+|------|--------------|----------------|-----------|
+| `podcastProgressRoutes.js` | `import { authMiddleware }` | `import { protect }` | Export is named `protect`, not `authMiddleware` |
+| `calendarSyncService.js` | `import sql from '../config/database.js'` | `import sql from '../config/sql.js'` | `database.js` exports `connectDatabase()`, not `sql` |
+| `announcementService.js` | `import fetch from 'node-fetch'` | Remove import | Node 18+ has native `fetch` |
+
+### How to Fix
+
+#### 1. Fix Auth Middleware Import
+
+**Wrong:**
+```javascript
+import { authMiddleware } from '../middleware/auth.js';
+router.use(authMiddleware);
+```
+
+**Correct:**
+```javascript
+import { protect } from '../middleware/auth.js';
+router.use(protect);
+```
+
+**Why:** Check the actual exports in `auth.js`:
+```javascript
+export const protect = async (req, res, next) => { ... }
+export const authorize = (...roles) => { ... }
+// Note: There is NO authMiddleware export
+```
+
+#### 2. Fix Database Import
+
+**Wrong:**
+```javascript
+import sql from '../config/database.js';
+```
+
+**Correct:**
+```javascript
+import sql from '../config/sql.js';
+```
+
+**Why:** The database config has two files:
+- `sql.js` - Exports the postgres `sql` instance (for queries)
+- `database.js` - Exports `connectDatabase()` function (for initialization only)
+
+#### 3. Remove node-fetch Import
+
+**Wrong:**
+```javascript
+import fetch from 'node-fetch';
+```
+
+**Correct:**
+```javascript
+// Note: Using native fetch (Node 18+)
+// No import needed
+```
+
+**Why:** Node 18+ includes native `fetch`. The `node-fetch` package is only needed for Node 16 and earlier.
+
+---
+
+## Debugging Process
+
+### Step 1: Verify Current State
+
+```bash
+# Check what imports exist
+grep -n "authMiddleware\|protect" server/routes/podcastProgressRoutes.js
+grep -n "database\|sql" server/services/calendarSyncService.js
+grep -n "node-fetch\|fetch" server/services/announcementService.js
+```
+
+### Step 2: Check What Exports Actually Exist
+
+```bash
+# Check auth middleware exports
+grep -n "export" server/middleware/auth.js
+
+# Check what database config files exist and export
+ls server/config/ | grep -E "database|sql"
+head -30 server/config/database.js
+head -30 server/config/sql.js
+```
+
+### Step 3: Check Git History
+
+```bash
+# Find the commit that tried to fix this
+git log --oneline -10
+
+# See what that commit changed
+git show <commit-hash> --stat --name-only
+
+# Check if there's a revert
+git log --oneline | grep -i "revert"
+```
+
+### Step 4: Test Fixes
+
+```bash
+# Syntax check
+cd server && node --check server.js
+
+# Build test
+cd client && npm run build
+
+# Full start test
+npm run dev
+```
+
+---
+
+## Prevention
+
+### 1. Always Check Exports Before Importing
+
+Before writing an import, verify the export exists:
+
+```bash
+# Quick check for available exports
+grep "export" path/to/module.js
+```
+
+### 2. Use Consistent Naming Conventions
+
+If the project uses `protect` for auth middleware, don't assume `authMiddleware` exists.
+
+### 3. Document Module Contracts
+
+In `server/middleware/auth.js`:
+```javascript
+/**
+ * Auth Middleware Exports:
+ * - protect: Require authenticated user
+ * - authorize(...roles): Require specific roles
+ * - isAdmin: Require admin role
+ * - optionalAuth: Parse auth if present, continue if not
+ */
+```
+
+### 4. Use TypeScript or JSDoc
+
+TypeScript would catch these errors at compile time:
+```typescript
+// This would error: 'authMiddleware' is not exported from './auth.js'
+import { authMiddleware } from './auth.js';
+```
+
+### 5. Check Node Version for Native APIs
+
+Before using packages like `node-fetch`:
+```javascript
+// Check if native fetch exists
+if (typeof fetch === 'undefined') {
+  // Only import node-fetch for older Node versions
+  const { default: fetch } = await import('node-fetch');
+}
+```
+
+---
+
+## Related Patterns
+
+- [ES_MODULE_IMPORT_HOISTING_DOTENV.md](./ES_MODULE_IMPORT_HOISTING_DOTENV.md) - ES Module import timing issues
+- [PM2_ENVIRONMENT_VARIABLE_CACHING.md](../deployment-security/PM2_ENVIRONMENT_VARIABLE_CACHING.md) - Server restart issues
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Assuming export names** - Always verify the actual export name
+- ❌ **Copying import patterns from other files** - Module structures vary
+- ❌ **Not checking git history** - Reverts can hide valid fixes
+- ❌ **Trusting initial error reports** - Symptoms often mislead (react-quill CSS vs server imports)
+- ❌ **Ignoring Node version differences** - Native APIs vary by version
+
+---
+
+## Diagnostic Commands Reference
+
+```bash
+# Check all exports in a file
+grep -n "export" path/to/file.js
+
+# Find all files importing a module
+grep -r "from './auth" server/
+
+# Check git for when a file was created
+git log --oneline -- path/to/file.js
+
+# See what a specific commit changed
+git show <hash> --stat
+
+# Check Node version
+node --version
+
+# Syntax check without running
+node --check server/server.js
+```
+
+---
+
+## Time to Implement
+
+**Fix Time:** 5-10 minutes once root cause identified
+**Debug Time:** 30-60 minutes (following this pattern)
+
+## Difficulty Level
+
+⭐⭐⭐ (3/5) - Moderate difficulty due to misdirection from initial symptom
+
+---
+
+**Author Notes:**
+
+The key insight from this debugging session: **Don't trust the initial error report**. The handoff said "react-quill CSS import" but that was a red herring. The real issues were three separate server import errors that shared no relationship to react-quill.
+
+**Always verify:**
+1. What files were recently changed?
+2. What do those files actually import?
+3. Do those exports actually exist?
+4. Was there a fix attempt that got reverted?
+
+The debugging process took longer than the fix because the symptom pointed the wrong direction. Once we traced the git history and checked the actual exports, the fix was trivial.
+
+---
+
+**Session Context:** 2026-01-28 - Phase 3.4 Student Activity Timeline import fixes
+**Commit:** e9ecd45
+**Files Fixed:**
+- `server/routes/podcastProgressRoutes.js`
+- `server/services/calendarSyncService.js`
+- `server/services/announcementService.js`

package/skills-library/patterns-standards/PYNPUT_GLOBAL_HOTKEY_VK_MATCHING.md

@@ -0,0 +1,252 @@
+# Pynput Global Hotkeys with Virtual Key Code Matching
+
+## The Problem
+
+Building a Windows desktop app with global hotkey detection (e.g., Ctrl+Shift+M for hold-to-talk). Two obstacles:
+
+1. **`keyboard` library (v0.13.5) is broken on Python 3.13+** — its low-level Windows hooks (`SetWindowsHookEx`) install and the listener thread starts, but callbacks never fire. The library was last updated in 2020 and has no fix.
+
+2. **Modifier keys corrupt `pynput` char values** — when Ctrl is held, pressing a letter key changes its `.char` attribute via Windows' control-character mapping (Ctrl+M → `'\r'`, Ctrl+D → `'\x04'`, Ctrl+A → `'\x01'`). Naive char-based matching silently fails for every Ctrl+letter combo.
+
+### Impact
+
+- Hotkeys appear to register (no errors) but never fire — completely silent failure
+- Extremely hard to debug because the hook thread is alive, the listener is running, everything *looks* correct
+- Every Ctrl+letter hotkey is affected (26 possible combos), not just edge cases
+
+---
+
+## The Solution
+
+### Root Cause
+
+**Issue 1:** The `keyboard` library's `_winkeyboard.py` uses internal threading and ctypes patterns that broke with Python 3.13+'s threading changes. The hook message pump thread runs but never delivers events to callbacks.
+
+**Issue 2:** Windows translates Ctrl+letter keypresses into ASCII control characters at the API level. When pynput's hook receives Ctrl+M, the OS reports `char='\r'` (carriage return, 0x0D) instead of `char='m'`. But the **virtual key code (`vk`)** remains `77` (= `ord('M')`) regardless of modifiers.
+
+### The Fix: Use pynput with VK-based matching
+
+Replace `keyboard` with `pynput.keyboard.Listener` and match keys by `vk` (virtual key code) instead of `char`.
+
+```python
+from pynput.keyboard import Key, Listener, KeyCode
+
+# WRONG: Match by char — fails when Ctrl is held
+def _to_key_bad(name: str):
+    return KeyCode.from_char(name)  # KeyCode(char='m')
+
+def _match_bad(key, target) -> bool:
+    # ctrl+m gives key.char='\r', target.char='m' → NEVER MATCHES
+    return key.char == target.char
+
+
+# RIGHT: Match by virtual key code — stable regardless of modifiers
+def _to_key_good(name: str):
+    return KeyCode.from_vk(ord(name.upper()))  # KeyCode(vk=77)
+
+def _match_good(key, target) -> bool:
+    key_vk = getattr(key, 'vk', None)
+    target_vk = getattr(target, 'vk', None)
+    if key_vk is not None and target_vk is not None:
+        return key_vk == target_vk
+    # Fallback for special keys
+    return key == target
+```
+
+### Full Hold-to-Talk Hotkey Manager Pattern
+
+```python
+from pynput.keyboard import Key, Listener, KeyCode
+import time
+
+# Map config strings → sets of pynput Key objects (left, right, generic)
+_MODIFIER_MAP = {
+    "ctrl": {Key.ctrl_l, Key.ctrl_r, Key.ctrl},
+    "shift": {Key.shift_l, Key.shift_r, Key.shift},
+    "alt": {Key.alt_l, Key.alt_r, Key.alt},
+}
+
+class HotkeyManager:
+    def __init__(self, hotkey_str: str, on_start, on_stop):
+        parts = hotkey_str.lower().split("+")
+        trigger_name = parts[-1]
+        self._mod_names = parts[:-1]
+
+        # Use vk for letter keys, Key enum for special keys
+        if len(trigger_name) == 1:
+            self._trigger = KeyCode.from_vk(ord(trigger_name.upper()))
+        else:
+            self._trigger = _SPECIAL_KEYS[trigger_name]  # Key.space, etc.
+
+        self._on_start = on_start
+        self._on_stop = on_stop
+        self._active = False
+        self._held_mods: set[Key] = set()
+        self._debounce_s = 0.2
+        self._last_time = 0.0
+        self._listener = None
+
+    def _key_matches(self, key, target) -> bool:
+        if key == target:
+            return True
+        if isinstance(key, KeyCode) and isinstance(target, KeyCode):
+            key_vk = getattr(key, 'vk', None)
+            target_vk = getattr(target, 'vk', None)
+            if key_vk is not None and target_vk is not None:
+                return key_vk == target_vk
+        return False
+
+    def _mods_held(self) -> bool:
+        for mod_name in self._mod_names:
+            if not (self._held_mods & _MODIFIER_MAP.get(mod_name, set())):
+                return False
+        return True
+
+    def _on_press(self, key):
+        # Track modifier state
+        for mod_keys in _MODIFIER_MAP.values():
+            if key in mod_keys:
+                self._held_mods.add(key)
+                return
+
+        now = time.monotonic()
+        if (
+            self._key_matches(key, self._trigger)
+            and not self._active
+            and self._mods_held()
+            and (now - self._last_time) > self._debounce_s
+        ):
+            self._active = True
+            self._last_time = now
+            self._on_start()
+
+    def _on_release(self, key):
+        # Modifier released while active → stop
+        for mod_keys in _MODIFIER_MAP.values():
+            if key in mod_keys:
+                self._held_mods.discard(key)
+                if self._active:
+                    self._active = False
+                    self._on_stop()
+                return
+
+        # Trigger key released → stop
+        if self._key_matches(key, self._trigger) and self._active:
+            self._active = False
+            self._on_stop()
+
+    def register(self):
+        self._listener = Listener(on_press=self._on_press, on_release=self._on_release)
+        self._listener.start()
+
+    def unregister(self):
+        if self._listener:
+            self._listener.stop()
+            self._listener = None
+```
+
+### Critical Design Decisions
+
+| Decision | Why |
+|----------|-----|
+| `KeyCode.from_vk(ord(name.upper()))` | VK codes are stable when modifiers are held. `from_char()` produces chars that get corrupted by Ctrl. |
+| `{Key.ctrl_l, Key.ctrl_r, Key.ctrl}` in modifier map | pynput sometimes reports `Key.ctrl` (generic) instead of `Key.ctrl_l`/`Key.ctrl_r`. Must accept all three. |
+| Modifier release also triggers stop | For hold-to-talk: releasing ANY part of the combo should stop. User might release Ctrl before M. |
+| 200ms debounce | Prevents double-firing from key repeat when holding the combo. |
+| `set` for held modifiers | O(1) intersection check with `_MODIFIER_MAP` sets. |
+
+---
+
+## Windows Ctrl+Key Character Mapping Reference
+
+| Combo | `.char` received | `.vk` | ASCII Control |
+|-------|-----------------|-------|---------------|
+| Ctrl+A | `'\x01'` | 65 | SOH |
+| Ctrl+C | `'\x03'` | 67 | ETX |
+| Ctrl+D | `'\x04'` | 68 | EOT |
+| Ctrl+M | `'\r'` (0x0D) | 77 | CR |
+| Ctrl+H | `'\x08'` | 72 | BS |
+| Ctrl+I | `'\t'` (0x09) | 73 | HT |
+| Ctrl+J | `'\n'` (0x0A) | 74 | LF |
+| Ctrl+[ | `'\x1b'` | 219 | ESC |
+
+Every letter A-Z maps to control code `0x01`-`0x1A` when Ctrl is held. VK is always `ord(letter.upper())`.
+
+---
+
+## Testing the Fix
+
+```python
+from pynput.keyboard import Key, Controller, Listener, KeyCode
+import time
+
+results = {'start': 0, 'stop': 0}
+hm = HotkeyManager("ctrl+shift+m",
+    on_start=lambda: results.update({'start': results['start']+1}),
+    on_stop=lambda: results.update({'stop': results['stop']+1}))
+hm.register()
+time.sleep(0.3)
+
+kb = Controller()
+kb.press(Key.ctrl_l); kb.press(Key.shift_l)
+time.sleep(0.1)
+kb.press('m'); time.sleep(0.3); kb.release('m')
+time.sleep(0.1)
+kb.release(Key.shift_l); kb.release(Key.ctrl_l)
+time.sleep(0.3)
+
+hm.unregister()
+assert results['start'] == 1 and results['stop'] >= 1
+```
+
+---
+
+## Prevention
+
+1. **Never use `keyboard` library with Python 3.13+** — hooks install silently but fire zero events
+2. **Never match pynput keys by `.char` when Ctrl is a modifier** — char is corrupted by OS
+3. **Always use `KeyCode.from_vk()` for letter keys** in hotkey registration
+4. **Include `Key.ctrl` (generic)** alongside `Key.ctrl_l`/`Key.ctrl_r` in modifier maps — pynput behavior varies
+5. **Kill stale instances** before debugging hotkey issues — multiple processes registering hooks can cause Windows to silently disable them
+
+---
+
+## Common Mistakes to Avoid
+
+- Using `keyboard.on_press_key()` on Python 3.13+ (silent failure, no error)
+- Using `KeyCode.from_char('m')` then comparing with `==` against a key pressed with Ctrl held
+- Only checking `Key.shift_l` / `Key.ctrl_l` without the generic `Key.shift` / `Key.ctrl`
+- Forgetting modifier-release-as-stop for hold-to-talk patterns (user releases Ctrl before the trigger key)
+- Not debouncing — key repeat fires rapid press events when holding a combo
+
+---
+
+## Related Patterns
+
+- Hold-to-talk audio recording: pair with `sounddevice` for mic capture
+- System tray integration: `pystray` runs on main thread, hotkey listener runs in background thread
+- Frozen mode detection: `getattr(sys, 'frozen', False)` for PyInstaller builds
+
+---
+
+## Resources
+
+- [pynput documentation](https://pynput.readthedocs.io/)
+- [keyboard library (abandoned)](https://github.com/boppreh/keyboard) — last release 0.13.5 (2020)
+- [Windows Virtual Key Codes](https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes)
+- [ASCII Control Characters](https://en.wikipedia.org/wiki/ASCII#Control_characters)
+
+---
+
+## Time to Implement
+
+**15-30 minutes** to replace `keyboard` with the pynput pattern. Most time spent discovering the char corruption issue.
+
+## Difficulty Level
+
+Stars: 3/5 — The fix itself is straightforward once you understand the root cause. The difficulty is **diagnosing** it: hooks install without error, listener threads are alive, everything looks correct, but callbacks never fire (keyboard lib) or silently mismatch (char corruption).
+
+---
+
+**Author Notes:**
+The two traps here are *silent*. The `keyboard` library doesn't throw errors — its hooks just never fire on Python 3.13+. And pynput's char corruption doesn't throw errors either — `'\r' != 'm'` just evaluates to False and your hotkey silently never triggers. The VK code is the only stable identifier across all modifier states.

package/skills-library/patterns-standards/REACT_USEEFFECT_CASCADE_RESET_FIX.md

@@ -0,0 +1,132 @@
+# React useEffect Cascade Reset Fix
+
+## Problem
+
+Custom hooks with cascading dropdown state (e.g., Book → Chapter → Verse) use `useEffect` chains where selecting a parent resets child values to `null`. When programmatically navigating to a specific location (e.g., clicking a search result to jump to Genesis 3:15), the cascade effects fire and **destroy the child selections** before the UI can render them.
+
+**Symptoms:**
+- Clicking a search result navigates to the correct book/chapter but verse is not highlighted
+- Programmatic navigation sets all three values, but useEffect on book change wipes chapter/verse
+- The chapter effect then fires again and wipes the verse
+
+## Root Cause
+
+React's `useEffect` chains create a cascade:
+
+```
+setSelectedBook("Genesis")  →  useEffect[selectedBook] fires  →  setSelectedChapter(null) ← DESTROYS
+                                                                   setSelectedVerse(null)  ← DESTROYS
+setSelectedChapter(3)       →  useEffect[selectedChapter] fires →  setSelectedVerse(null) ← DESTROYS
+setSelectedVerse(15)        →  Already nullified by cascade
+```
+
+Even though all three `setState` calls happen synchronously, React batches them but the effects still run in order, each one resetting the children.
+
+## Solution: Programmatic Navigation Ref Guard
+
+Use a `useRef` flag to skip cascade resets during programmatic navigation:
+
+```typescript
+import { useState, useEffect, useCallback, useRef } from 'react'
+
+export function useCascadingNavigation() {
+  const [selectedBook, setSelectedBook] = useState<string | null>(null)
+  const [selectedChapter, setSelectedChapter] = useState<number | null>(null)
+  const [selectedVerse, setSelectedVerse] = useState<number | null>(null)
+
+  // Ref to skip cascade resets during programmatic navigation
+  const programmaticNavRef = useRef(false)
+
+  // Update chapters when book changes
+  useEffect(() => {
+    if (selectedBook) {
+      const chapterCount = getChapterCount(selectedBook)
+      setChapters(Array.from({ length: chapterCount }, (_, i) => i + 1))
+
+      // Skip reset during programmatic navigation
+      if (!programmaticNavRef.current) {
+        setSelectedChapter(null)
+        setSelectedVerse(null)
+      }
+    }
+  }, [selectedBook])
+
+  // Update verses when chapter changes
+  useEffect(() => {
+    if (selectedBook && selectedChapter) {
+      fetchVerseCount(selectedBook, selectedChapter)
+
+      // Skip verse reset during programmatic navigation
+      if (!programmaticNavRef.current) {
+        setSelectedVerse(null)
+      }
+      // Reset flag after chapter effect processes
+      programmaticNavRef.current = false
+    }
+  }, [selectedBook, selectedChapter])
+
+  // Navigate to a specific location without cascade resets
+  const navigateToVerse = useCallback((book: string, chapter: number, verse: number) => {
+    programmaticNavRef.current = true
+    setSelectedBook(book)
+    setSelectedChapter(chapter)
+    setSelectedVerse(verse)
+  }, [])
+
+  // Safety cleanup: ensure flag is always reset after effects process
+  useEffect(() => {
+    programmaticNavRef.current = false
+  })
+
+  return {
+    selectedBook, setSelectedBook,
+    selectedChapter, setSelectedChapter,
+    selectedVerse, setSelectedVerse,
+    navigateToVerse,  // Use this for programmatic navigation
+  }
+}
+```
+
+### Key Implementation Details
+
+1. **`programmaticNavRef`** — A ref (not state) because it needs to be set synchronously before effects run, without triggering re-renders.
+
+2. **Flag reset location** — The flag is reset in the **chapter effect** (the last cascade effect that needs guarding), not immediately after setting state. This ensures the flag persists through all cascade effects.
+
+3. **Safety cleanup effect** — An unconditional `useEffect(() => { programmaticNavRef.current = false })` with no dependency array runs after every render, ensuring the flag is always cleaned up even if an effect chain is interrupted.
+
+4. **Consumer usage** — Components call `navigateToVerse()` instead of individual setters:
+
+```typescript
+// In BibleViewer.tsx (consumer component)
+const { navigateToVerse } = useBibleNavigation()
+
+useEffect(() => {
+  if (navigateTo && navigateTo !== prevNavigateToRef.current) {
+    prevNavigateToRef.current = navigateTo
+    navigateToVerse(navigateTo.book, navigateTo.chapter, navigateTo.verse)
+  }
+}, [navigateTo, navigateToVerse])
+```
+
+## When to Apply This Pattern
+
+- Any cascading dropdown hook (Country → State → City)
+- Multi-level navigation (Book → Chapter → Verse, Category → Subcategory → Item)
+- Any hook where parent selection resets child selections, AND you need programmatic deep navigation
+- Search result → detail view navigation
+
+## Anti-Patterns to Avoid
+
+1. **Don't use state for the flag** — `useState` triggers re-renders and the flag won't be set before effects run
+2. **Don't set all values in a single effect** — Still triggers cascades because each `setState` triggers dependent effects
+3. **Don't try `flushSync`** — Doesn't prevent effect cascades, just forces synchronous DOM updates
+4. **Don't remove the cascade resets entirely** — Manual dropdown selection genuinely needs child resets
+
+## Tech Stack
+- React 18+ (hooks, useRef, useEffect, useCallback)
+- TypeScript
+- Any UI framework with cascading state
+
+## Tags
+`react` `useEffect` `cascade` `useState` `navigation` `dropdown` `useRef` `programmatic-navigation`