@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/_general/api-patterns/streaming-command-timeout.md

@@ -0,0 +1,122 @@
+---
+name: streaming-command-timeout
+category: api-patterns
+version: 1.0.0
+contributed: 2026-03-12
+contributor: c3-server
+last_updated: 2026-03-12
+contributors:
+  - c3-server
+tags: [bun, node, process, timeout, streaming, pm2, ssh, spawn]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# Streaming Command Timeout — Preventing Hanging Process Execution
+
+## Problem
+
+When executing shell commands via `Bun.spawn` or `child_process.spawn`, some commands are streaming by default and never exit (e.g., `pm2 logs`, `tail -f`, `docker logs -f`). If you `await` their stdout, the process hangs forever — the API endpoint never responds, the UI spinner runs indefinitely, and server resources are leaked.
+
+**Symptoms:**
+- UI button spins forever after clicking "View Logs"
+- API endpoint never returns a response
+- Server eventually runs out of file descriptors or memory
+- `pm2 logs` (without `--nostream`) never exits
+- SSH commands to remote servers hang if the remote command streams
+
+## Solution Pattern
+
+Two-layer defense:
+
+1. **Fix the command itself:** Add flags that make commands exit after producing output (`--nostream`, `--lines N`, `-n N`)
+2. **Add a timeout wrapper:** Use `Promise.race` between process completion and a timeout timer. On timeout, kill the process and return partial output.
+
+## Code Example
+
+```typescript
+// Before (hangs forever on streaming commands)
+const proc = Bun.spawn(['bash', '-c', 'pm2 logs --lines 30'], {
+  stdout: 'pipe', stderr: 'pipe'
+})
+const stdout = await new Response(proc.stdout).text()  // HANGS FOREVER
+
+// After (exits cleanly with timeout protection)
+const ACTION_TIMEOUT_MS = 30_000
+
+const proc = Bun.spawn(['bash', '-c', 'pm2 logs --lines 30 --nostream'], {
+  stdout: 'pipe', stderr: 'pipe'
+})
+
+const timeout = new Promise<'timeout'>((resolve) =>
+  setTimeout(() => resolve('timeout'), ACTION_TIMEOUT_MS)
+)
+
+const result = await Promise.race([
+  (async () => {
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    const exitCode = await proc.exited
+    return { stdout, stderr, exitCode } as const
+  })(),
+  timeout,
+])
+
+if (result === 'timeout') {
+  proc.kill()
+  const partial = await Promise.race([
+    new Response(proc.stdout).text(),
+    new Promise<string>((r) => setTimeout(() => r(''), 1000)),
+  ])
+  return {
+    output: (partial || '') + '\n[Timed out after 30s]',
+    success: true,  // Partial output is still useful
+  }
+}
+```
+
+## Implementation Steps
+
+1. Audit all commands that can stream: `pm2 logs`, `docker logs`, `tail`, `ssh` with streaming remotes
+2. Add exit flags: `--nostream`, `--lines N`, `-n N`
+3. Wrap execution in `Promise.race` with a timeout (30s is reasonable for most commands)
+4. On timeout: kill process, collect partial output, return with timeout notice
+5. Return partial output as success (user still gets useful data)
+
+## Common Streaming Commands & Fixes
+
+| Command | Fix |
+|---------|-----|
+| `pm2 logs` | Add `--nostream` |
+| `docker logs` | Remove `-f`, add `--tail N` |
+| `tail -f` | Use `tail -n N` instead |
+| `ssh ... 'pm2 logs'` | Add `--nostream` to remote command |
+| `kubectl logs -f` | Remove `-f`, add `--tail N` |
+
+## When to Use
+
+- Any API endpoint that executes shell commands
+- Quick action / one-click command systems
+- Remote command execution via SSH
+- CI/CD pipeline step execution
+- Any `Bun.spawn` / `child_process.spawn` where the command set is user-configurable
+
+## When NOT to Use
+
+- SSE/WebSocket streaming endpoints (you WANT streaming there)
+- Background jobs with their own lifecycle management
+- Commands you've verified always exit quickly
+
+## Common Mistakes
+
+- Setting timeout too short (5s) — SSH commands to remote servers can take 10-15s to connect
+- Killing the process but not collecting partial output — user gets "timeout" with no useful data
+- Forgetting to clean up the timeout timer on successful completion (minor memory leak)
+- Not adding `--nostream` AND adding timeout — the timeout alone works but wastes 30s every time
+
+## References
+
+- Bun docs: `Bun.spawn` API
+- PM2 docs: `--nostream` flag (outputs then exits)
+- Contributed from: c3-server action executor (PM2 logs hanging forever)

package/skills-library/_general/api-patterns/streaming-proxy-cors-bypass.md

@@ -0,0 +1,102 @@
+---
+name: streaming-proxy-cors-bypass
+category: api-patterns
+version: 1.0.0
+contributed: 2026-03-12
+contributor: mern-community-lms
+last_updated: 2026-03-12
+contributors:
+  - mern-community-lms
+tags: [cors, proxy, streaming, pipeline, node, express, video, cdn]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Streaming Proxy CORS Bypass
+
+## Problem
+
+Third-party CDNs (Zoom, Vimeo, cloud storage) serve media files without CORS headers. When your frontend tries to play or fetch these URLs directly, the browser blocks the request with a CORS error. A common workaround is to redirect the client (302) to the CDN URL, but this still fails because the browser's media element follows the redirect and hits the same CORS wall.
+
+**Symptoms:**
+- Video/audio playback fails silently or shows "blocked by CORS policy"
+- `fetch()` to CDN URLs returns opaque responses or errors
+- 302 redirects work in Postman but fail in browser
+- `Access-Control-Allow-Origin` header missing from CDN response
+
+## Solution Pattern
+
+Instead of redirecting the client to the CDN, your server acts as a **streaming proxy** — it fetches the CDN resource server-side (no CORS restriction) and pipes the response body directly to the client using Node.js `stream.pipeline()`. The client only talks to your origin server, so CORS is never an issue.
+
+**Key insight:** Server-to-server requests are not subject to CORS. By interposing your server as a transparent pipe, you eliminate the browser's CORS check entirely while adding minimal latency (streaming, not buffering).
+
+## Code Example
+
+```javascript
+// Before (broken — 302 redirect hits CORS wall)
+app.get('/api/video/replay/:meetingId', async (req, res) => {
+  const downloadUrl = await getZoomDownloadUrl(req.params.meetingId);
+  res.redirect(downloadUrl); // Browser follows redirect, CDN blocks CORS
+});
+
+// After (streaming proxy — no CORS issue)
+import { pipeline } from 'stream/promises';
+
+app.get('/api/video/replay/:meetingId', async (req, res) => {
+  const downloadUrl = await getZoomDownloadUrl(req.params.meetingId);
+
+  const cdnResponse = await fetch(downloadUrl, { redirect: 'follow' });
+
+  if (!cdnResponse.ok) {
+    return res.status(cdnResponse.status).json({ error: 'CDN fetch failed' });
+  }
+
+  // Forward content headers
+  res.set('Content-Type', cdnResponse.headers.get('content-type') || 'video/mp4');
+  const contentLength = cdnResponse.headers.get('content-length');
+  if (contentLength) res.set('Content-Length', contentLength);
+
+  // Stream body directly — no buffering in memory
+  await pipeline(cdnResponse.body, res);
+});
+```
+
+## Implementation Steps
+
+1. Replace `res.redirect(cdnUrl)` with a server-side `fetch(cdnUrl)`
+2. Forward relevant headers (`Content-Type`, `Content-Length`, `Content-Disposition`)
+3. Use `stream.pipeline()` (or `pipe()`) to stream the response body to the client
+4. Handle errors — if CDN returns 403/404, return a clean error to client
+5. For authenticated CDNs (Zoom, AWS S3), add auth headers/tokens to the server-side fetch
+
+## When to Use
+
+- CDN serves media without CORS headers and you can't control the CDN config
+- Third-party API returns download URLs that work server-side but not in browsers
+- You need to proxy large files without buffering them entirely in memory
+- OAuth-protected downloads (Zoom, Google Drive) where tokens can't be exposed to client
+
+## When NOT to Use
+
+- You control the CDN and can add CORS headers directly (simpler)
+- The CDN already includes proper `Access-Control-Allow-Origin` headers
+- Files are small enough to buffer — just use `res.send(await fetch(url).then(r => r.buffer()))`
+- Static assets that should be served from a CDN for performance (proxy adds latency)
+
+## Common Mistakes
+
+- **Buffering the entire file in memory** — use `pipeline()` for streaming, not `await response.buffer()`
+- **Not following redirects** — CDN URLs often redirect; use `{ redirect: 'follow' }` in fetch
+- **Forgetting Content-Type** — browser won't play video if header is `application/octet-stream`
+- **Not handling CDN auth expiry** — Zoom/S3 signed URLs expire; refresh token before proxying
+
+## Related Skills
+
+- [streaming-command-timeout](../api-patterns/streaming-command-timeout.md) — Timeout handling for streaming operations
+
+## References
+
+- Node.js `stream.pipeline()` documentation
+- Zoom Server-to-Server OAuth API
+- Contributed from: mern-community-lms (Zoom replay fix, 2026-03-12)

package/skills-library/_general/automation/settings-gui-generator.md

@@ -0,0 +1,172 @@
+---
+name: settings-gui-generator
+category: automation
+version: 1.0.0
+contributed: 2026-02-24
+contributor: voice-bridge-v4
+last_updated: 2026-02-24
+contributors:
+  - voice-bridge-v4
+tags: [pyqt6, python, settings, config, code-generation, yaml, dark-theme, gui]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Settings GUI Generator (Config-to-Dialog Pattern)
+
+## Problem
+
+Every Python desktop app with a YAML/JSON/TOML config file eventually needs a settings dialog. The typical anti-pattern:
+- `os.startfile(config_path)` opens raw YAML in Notepad
+- Users break YAML indentation
+- No discoverability — users can't see what options exist
+- No validation — invalid values crash at runtime
+- No live reload — changes require full restart
+
+Building a settings dialog from scratch takes 30-60 minutes and commonly hits the **cross-thread bug** when called from pystray callbacks.
+
+## Solution Pattern
+
+Map config structure to PyQt6 widgets automatically:
+
+| Config Type | Widget | Example |
+|-------------|--------|---------|
+| `boolean` | QCheckBox | `enabled: true` → ☑ Enabled |
+| `string` (enum) | QComboBox | `backend: "piper"` → dropdown [piper, edge] |
+| `number` | QSpinBox / QSlider | `speed: 1.0` → slider 0.5-2.0 |
+| `string` (free) | QLineEdit | `voice: "en_US-lessac"` → text input |
+| Nested dict with `enabled` | QCheckBox in QGroupBox | Feature group toggle |
+
+### Thread-Safety Pattern (CRITICAL)
+
+System tray callbacks (pystray) run on a background thread. Qt widgets MUST be created on the Qt GUI thread. The dialog will RENDER but be UNCLICKABLE if created from the wrong thread.
+
+**Solution:** Signal marshaling:
+
+```python
+# In overlay/main window:
+sig_open_settings = pyqtSignal()  # Thread-safe bridge
+
+# Tray callback (WRONG thread):
+def _open_settings(self):
+    self.overlay.sig_open_settings.emit()  # Just emit signal
+
+# Qt slot (RIGHT thread, auto-marshaled):
+def _on_open_settings(self):
+    from .settings_dialog import SettingsDialog
+    dialog = SettingsDialog(self)
+    dialog.settings_changed.connect(self._on_settings_changed)
+    dialog.exec()
+```
+
+## Code Example
+
+```python
+# Before (problematic) — opens raw YAML in Notepad
+def _open_settings(self) -> None:
+    os.startfile(str(CONFIG_FILE))
+
+# After (solution) — proper settings GUI with live reload
+class SettingsDialog(QDialog):
+    settings_changed = pyqtSignal(dict)
+
+    def __init__(self, parent=None):
+        super().__init__(parent)
+        self.config = load_config()
+        self._widgets = {}  # config_path → widget mapping
+        self._build_ui()
+
+    def _build_ui(self):
+        features = [
+            ("post_processing.hallucination_filter", "Hallucination Filter",
+             "Reject garbage like 'thank you for watching'"),
+            ("post_processing.filler_removal", "Filler Removal",
+             "Strip um, uh, like, basically"),
+        ]
+        for path, label, desc in features:
+            cb = QCheckBox(f"{label}\n{desc}")
+            value = self._get_nested(self.config, path)
+            cb.setChecked(value.get("enabled", False))
+            self._widgets[path] = cb
+
+    def _save(self):
+        config = load_config()  # Fresh read!
+        for path, widget in self._widgets.items():
+            self._set_nested(config, path, "enabled", widget.isChecked())
+        save_config(config)
+        self.settings_changed.emit(config)
+        self.accept()
+```
+
+### Dark Theme Stylesheet
+
+```python
+STYLESHEET = """
+QDialog { background-color: #0f0f14; color: #f0f0f5; }
+QGroupBox {
+    background-color: #1a1a24; border: 1px solid #2a2a3a;
+    border-radius: 8px; margin-top: 12px; padding: 16px;
+}
+QGroupBox::title { color: #6366f1; }
+QCheckBox::indicator:checked {
+    background-color: #6366f1; border-color: #6366f1;
+}
+QPushButton {
+    background-color: #6366f1; color: white;
+    border-radius: 6px; padding: 8px 24px;
+}
+"""
+```
+
+### Live Reload Pattern
+
+```python
+def _on_settings_changed(self, new_config: dict):
+    self.text_processor = TextProcessor(new_config)  # Recreate from config
+    # No restart needed — next call uses new settings
+```
+
+## Implementation Steps
+
+1. Create `settings_dialog.py` alongside your main module
+2. Define feature list as `(config_path, label, description)` tuples
+3. Map each config type to appropriate Qt widget
+4. Build UI with QGroupBox sections for logical grouping
+5. Wire save button: load_config() fresh → apply widget states → save_config()
+6. Emit `settings_changed` signal with full config dict
+7. In main app: connect signal via Qt signal (NOT direct call from tray)
+8. Add fallback to `os.startfile()` if dialog import fails
+
+## When to Use
+
+- Any Python desktop app with a YAML/JSON/TOML config file
+- When "Settings" currently opens the raw config in a text editor
+- When features are togglable and users shouldn't understand config syntax
+- When you want live reload without full app restart
+
+## When NOT to Use
+
+- Web apps (use a proper web settings page)
+- CLI-only tools (use command-line flags)
+- When config has only 1-2 simple values (overkill)
+- When config changes ALWAYS require restart (signal adds complexity)
+
+## Common Mistakes
+
+- **Cross-thread dialog creation** — The #1 bug. ALWAYS use signal marshaling from tray callbacks. The dialog renders but is unclickable without it.
+- **Reading stale config in `_save()`** — Always `load_config()` fresh before applying widget states
+- **Not handling nested dicts** — Config like `{post_processing: {filter: {enabled: true}}}` needs recursive navigation
+- **Missing deep_merge for defaults** — If config file doesn't have new feature sections, `deep_merge(DEFAULT_CONFIG, loaded)` ensures they appear
+- **Not writing defaults to disk** — After adding new features, call `load_config()` then `save_config()` to persist the merged defaults
+
+## Related Skills
+
+- [pyqt6-settings-dialog](../frontend/pyqt6-settings-dialog.md) — The pattern this generates
+- [togglable-processing-pipeline](../patterns-standards/togglable-processing-pipeline.md) — Config-driven feature ordering
+
+## References
+
+- Contributed from: voice-bridge-v4
+- Real implementation: `voice-bridge-v3/src/voice_bridge_v3/settings_dialog.py`
+- PyQt6 QDialog docs: https://doc.qt.io/qtforpython-6/PySide6/QtWidgets/QDialog.html

package/skills-library/_general/database-solutions/data-type-mapping-reference.md

@@ -0,0 +1,181 @@
+---
+name: data-type-mapping-reference
+category: database-solutions
+version: 1.0.0
+contributed: 2026-03-10
+contributor: research
+last_updated: 2026-03-10
+tags: [postgresql, mysql, sqlite, sql-server, data-types, migration, type-mapping]
+difficulty: medium
+---
+
+# Data Type Mapping Reference
+
+## Problem
+
+Database migrations fail silently when type mappings are wrong. Unsigned integers overflow, booleans store unexpected values, dates corrupt, and JSON loses indexability. Developers need a precise, copy-pasteable mapping table for every common type across PostgreSQL, MySQL, SQLite, and SQL Server.
+## Complete Type Mapping Table
+
+### Numeric Types
+
+| PostgreSQL | MySQL | SQLite | SQL Server | Migration Notes |
+|---|---|---|---|---|
+| `SMALLINT` | `SMALLINT` | `INTEGER` | `SMALLINT` | Direct mapping |
+| `INTEGER` | `INT` | `INTEGER` | `INT` | Direct mapping |
+| `BIGINT` | `BIGINT` | `INTEGER` | `BIGINT` | SQLite uses 8-byte INTEGER for all |
+| N/A | `TINYINT` (signed, -128 to 127) | `INTEGER` | `TINYINT` (unsigned, 0-255) | PG has no TINYINT — use SMALLINT |
+| N/A | `INT UNSIGNED` | `INTEGER` | N/A | PG: upsize to `BIGINT` for range |
+| `NUMERIC(p,s)` | `DECIMAL(p,s)` | `REAL` or `TEXT` | `DECIMAL(p,s)` | Validate precision alignment for financial data |
+| `REAL` (4 bytes) | `FLOAT` | `REAL` | `REAL` | Direct mapping |
+| `DOUBLE PRECISION` | `DOUBLE` | `REAL` | `FLOAT(53)` | Direct mapping |
+| `MONEY` | `DECIMAL(19,2)` | N/A | `MONEY` | Avoid PG MONEY — use NUMERIC(19,2) |
+
+**Unsigned integer rule:** MySQL `UNSIGNED INT` → PG `BIGINT` (upsize to accommodate 0-4.29B range). pgloader does this automatically.
+
+### String Types
+
+| PostgreSQL | MySQL | SQLite | SQL Server | Migration Notes |
+|---|---|---|---|---|
+| `CHAR(n)` | `CHAR(n)` (max 255) | `TEXT` | `CHAR(n)` (max 8000) | Check length limits |
+| `VARCHAR(n)` | `VARCHAR(n)` (max 65535) | `TEXT` | `VARCHAR(n)` / `VARCHAR(MAX)` | PG max ~10M; MySQL max 65K |
+| `TEXT` | `TEXT` (64KB) | `TEXT` | `TEXT` | MySQL TEXT is 64KB; use LONGTEXT for larger |
+| `TEXT` | `MEDIUMTEXT` (16MB) | `TEXT` | `VARCHAR(MAX)` | pgloader maps all → PG TEXT |
+| `TEXT` | `LONGTEXT` (4GB) | `TEXT` | `VARCHAR(MAX)` | pgloader maps all → PG TEXT |
+
+**Charset gotcha:** MySQL defaults to `latin1` in older versions. Always specify `utf8mb4` for full Unicode. PG is always UTF-8.
+
+### Boolean
+
+| PostgreSQL | MySQL | SQLite | SQL Server |
+|---|---|---|---|
+| `BOOLEAN` | `TINYINT(1)` / `BOOL` | `INTEGER` (0/1) | `BIT` |
+
+**pgloader rule:** MySQL `TINYINT(1)` → PG `BOOLEAN` (only when display width = 1).
+**Validation:** MySQL TINYINT(1) can store 0-127. Values > 1 have no boolean mapping — validate before migration.
+
+### Date / Time
+
+| PostgreSQL | MySQL | SQLite | SQL Server | Migration Notes |
+|---|---|---|---|---|
+| `DATE` | `DATE` | `TEXT` | `DATE` | Direct |
+| `TIME` | `TIME` | `TEXT` | `TIME(p)` | Direct |
+| `TIMESTAMP` | `DATETIME` | `TEXT` | `DATETIME2(p)` | MySQL DATETIME has no timezone |
+| `TIMESTAMPTZ` | `TIMESTAMP` | `TEXT` | `DATETIMEOFFSET(p)` | MySQL TIMESTAMP auto-converts UTC |
+| `INTERVAL` | N/A | N/A | N/A | PG-only — convert to seconds or use app logic |
+
+**Critical gotchas:**
+- MySQL `0000-00-00` and `0000-00-00 00:00:00` → PG: **rejected**. Convert to NULL.
+- MySQL `TIMESTAMP` range: 1970-2038. PG `TIMESTAMPTZ` range: 4713 BC - 294276 AD.
+- SQL Server `DATETIME2` precision 0-7; PG max precision 6 (microseconds truncated).
+- **pgloader rule:** MySQL `DATETIME`/`TIMESTAMP` → PG `TIMESTAMPTZ`.
+
+### Binary
+
+| PostgreSQL | MySQL | SQLite | SQL Server |
+|---|---|---|---|
+| `BYTEA` | `BINARY(n)` / `VARBINARY(n)` | `BLOB` | `BINARY(n)` / `VARBINARY(n)` |
+| `BYTEA` | `TINYBLOB/BLOB/MEDIUMBLOB/LONGBLOB` | `BLOB` | `IMAGE` (deprecated) |
+
+**pgloader rule:** All MySQL binary/BLOB variants → PG `BYTEA`.
+
+### UUID
+
+| PostgreSQL | MySQL | SQLite | SQL Server |
+|---|---|---|---|
+| `UUID` (native, 16 bytes) | `CHAR(36)` | `TEXT` | `UNIQUEIDENTIFIER` |
+| `gen_random_uuid()` | `UUID()` | N/A (app-side) | `NEWID()` |
+
+**MINISTRY-LMS lesson:** MySQL `LAST_INSERT_ID()` returns 0 for `CHAR(36)` PKs. Generate UUID in JavaScript with `uuidv4()` and include `id` in INSERT column list.
+
+### JSON
+
+| PostgreSQL | MySQL | SQLite | SQL Server | MariaDB |
+|---|---|---|---|---|
+| `JSON` (text, validated) | `JSON` (binary since 8.0) | `TEXT` or `JSON` (3.45+) | `NVARCHAR(MAX)` | `LONGTEXT` alias |
+| `JSONB` (binary, indexable) | N/A | `JSONB` (3.45+) | N/A | N/A |
+
+**Key difference:** PG JSONB supports containment (`@>`), existence (`?`), and GIN indexing. MySQL JSON requires generated columns + B-tree for indexing. MariaDB JSON is just LONGTEXT with no binary optimization.
+
+### Enum
+
+| PostgreSQL | MySQL | SQLite | SQL Server |
+|---|---|---|---|
+| `CREATE TYPE x AS ENUM(...)` | `ENUM(...)` inline on column | N/A | N/A |
+
+**pgloader rule:** MySQL inline ENUM → PG `CREATE TYPE enum_table_column AS ENUM(...)` + column reference.
+**Reverse (PG→MySQL):** Flatten CREATE TYPE into inline ENUM on each column that uses it.
+
+### PostgreSQL-Only Types (No Direct Equivalent)
+
+| PG Type | MySQL Workaround | SQLite Workaround | SQL Server Workaround |
+|---|---|---|---|
+| `TEXT[]` / `INT[]` | `JSON` (array) | `TEXT` (JSON) | `NVARCHAR(MAX)` (JSON) |
+| `JSONB` | `JSON` (lose GIN indexing) | `TEXT` | `NVARCHAR(MAX)` |
+| `CIDR` / `INET` | `VARCHAR(43)` | `TEXT` | `VARCHAR(43)` |
+| `MACADDR` | `VARCHAR(17)` | `TEXT` | `VARCHAR(17)` |
+| `TSVECTOR` / `TSQUERY` | FULLTEXT index (different API) | FTS5 extension | Full-text catalog |
+| `HSTORE` | `JSON` | `TEXT` | `NVARCHAR(MAX)` |
+| Geometric types | Spatial extensions | N/A | `GEOMETRY` |
+
+## pgloader Default Casting Rules (MySQL → PostgreSQL)
+
+```
+TINYINT(1)           → BOOLEAN
+TINYINT (other)      → SMALLINT
+INT UNSIGNED         → BIGINT
+INT AUTO_INCREMENT   → SERIAL
+BIGINT AUTO_INCREMENT → BIGSERIAL
+BIT(1)               → BOOLEAN
+DATETIME/TIMESTAMP   → TIMESTAMPTZ
+YEAR                 → INTEGER
+All TEXT variants    → TEXT
+All BLOB variants   → BYTEA
+ENUM(...)            → CREATE TYPE + column
+SET(...)             → TEXT
+0000-00-00 dates     → NULL
+```
+
+## Safest Portable Type Subset
+
+These types work identically across PG, MySQL, SQLite, and SQL Server with zero translation:
+
+```
+STRING:    VARCHAR(n) where n ≤ 255
+INTEGER:   INT / INTEGER
+FLOAT:     REAL / DOUBLE PRECISION
+BOOLEAN:   Use INTEGER 0/1 (universally supported)
+TEXT:      TEXT (for unlimited strings)
+TIMESTAMP: Store as ISO 8601 TEXT for max portability
+UUID:      CHAR(36) (string representation)
+JSON:      TEXT containing valid JSON (parse in app layer)
+```
+
+**Trade-off:** This subset sacrifices database-specific optimizations (JSONB indexing, native UUID, array types) for portability.
+
+## When to Use
+
+- Planning any database migration
+- Choosing column types for cross-database applications
+- Configuring pgloader / SQLines custom type mappings
+- Reviewing ORM schema definitions for portability issues
+- Building the DATABASE phase of `/fire-resurrect`
+
+## When NOT to Use
+
+- Single-database projects committed to one vendor
+- NoSQL databases
+- Data warehouse columns (different optimization concerns)
+
+## Related Skills
+
+- [sql-dialect-compatibility-matrix](sql-dialect-compatibility-matrix.md)
+- [pg-to-mysql-schema-migration-methodology](pg-to-mysql-schema-migration-methodology.md)
+- [mysql-to-pg-migration](mysql-to-pg-migration.md)
+
+## References
+
+- pgloader MySQL documentation — default casting rules
+- MySQL Workbench PostgreSQL type mapping reference
+- SQLines data type mapping configuration
+- MINISTRY-LMS sql-compat.js — production-proven type handling
+- "I Migrated 400M Rows" (Medium, 2026) — type mapping breakage points

package/skills-library/_general/database-solutions/mysql-limit-offset-string-coercion.md

@@ -0,0 +1,102 @@
+---
+name: mysql-limit-offset-string-coercion
+category: database-solutions
+version: 1.0.0
+contributed: 2026-03-07
+contributor: ministry-lms
+last_updated: 2026-03-07
+contributors:
+  - ministry-lms
+tags: [mysql, mariadb, postgresql, limit, offset, pagination, express, req-query, type-coercion]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# MySQL LIMIT/OFFSET String Coercion
+
+## Problem
+
+When porting a PostgreSQL application to MySQL, paginated endpoints break with SQL syntax errors. The root cause: Express `req.query` parameters are always strings (`'20'`, not `20`). PostgreSQL silently auto-casts `LIMIT '20'` to `LIMIT 20`. MySQL strictly rejects string values in LIMIT/OFFSET clauses.
+
+**Symptoms:**
+- `You have an error in your SQL syntax` on any paginated endpoint
+- Works fine in PostgreSQL, breaks in MySQL
+- Only affects endpoints that pass `req.query.limit` or `req.query.page` into SQL
+- Error appears as `LIMIT '20' OFFSET 0` in the generated SQL
+
+## Solution Pattern
+
+Fix this **systemically** in the SQL compatibility/translation layer, not per-controller. Any runtime SQL translation layer that converts PG queries to MySQL should coerce LIMIT/OFFSET values from strings to integers before query execution.
+
+**Why systemic:** Fixing in every controller/model is fragile — each new paginated endpoint would need the same fix. One fix in the SQL layer covers all endpoints, past and future.
+
+## Code Example
+
+```javascript
+// Before (broken on MySQL)
+// req.query.limit = '20' (string from Express)
+const result = await sql`
+  SELECT * FROM meetings
+  ORDER BY created_at DESC
+  LIMIT ${limit} OFFSET ${offset}
+`;
+// Generated SQL: SELECT * FROM meetings ORDER BY created_at DESC LIMIT '20' OFFSET 0
+// MySQL error: You have an error in your SQL syntax
+
+// After (works on both PG and MySQL)
+// Option A: Fix in SQL compatibility layer (RECOMMENDED — one fix for all endpoints)
+// In the template literal parser, detect LIMIT/OFFSET context and coerce to int:
+const precedingSQL = sql.trimEnd().toUpperCase();
+if (typeof value === 'string' && /\b(LIMIT|OFFSET)\s*\??\s*$/.test(precedingSQL)) {
+  const parsed = parseInt(value, 10);
+  if (!isNaN(parsed)) value = parsed;
+}
+
+// Option B: Fix per-controller (NOT recommended — must repeat everywhere)
+const limit = parseInt(req.query.limit, 10) || 50;
+const offset = parseInt(req.query.page, 10) * limit || 0;
+```
+
+## Implementation Steps
+
+1. Locate the SQL template literal parser in your compatibility layer (the function that processes tagged template literals and generates parameterized queries)
+2. In the section that handles parameter values, check if the preceding SQL text ends with `LIMIT` or `OFFSET`
+3. If the value is a string and the context is LIMIT/OFFSET, coerce it to an integer with `parseInt(value, 10)`
+4. Only apply the coercion if `parseInt` produces a valid number (not `NaN`)
+5. Restart the server and test any paginated endpoint
+
+## When to Use
+
+- Porting a PostgreSQL Express app to MySQL/MariaDB
+- Building a SQL compatibility layer between PG and MySQL
+- Any scenario where `req.query` values pass through to LIMIT/OFFSET in MySQL
+- When you see `LIMIT '20'` style errors in MySQL logs
+
+## When NOT to Use
+
+- If your app already uses an ORM (Prisma, Sequelize, Knex) that handles type coercion
+- If you're only targeting PostgreSQL (PG handles this automatically)
+- If LIMIT/OFFSET values come from validated/parsed sources (not raw req.query)
+- If you're using prepared statements where the driver handles type binding
+
+## Common Mistakes
+
+- Fixing in individual controllers instead of the SQL layer (fragile, doesn't scale)
+- Using `Number()` instead of `parseInt()` (Number('') returns 0, parseInt('') returns NaN — different edge cases)
+- Forgetting OFFSET (same issue as LIMIT — both need coercion)
+- Not checking for NaN before coercing (could turn invalid input into NaN parameter)
+- Assuming `req.query` values are numbers (they are ALWAYS strings in Express)
+
+## Related Skills
+
+- [pg-to-mysql-schema-migration-methodology](../database-solutions/pg-to-mysql-schema-migration-methodology.md) - Schema-level PG to MySQL migration
+- [sql-injection-prevention-postgresjs](../../security/sql-injection-prevention-postgresjs.md) - Safe SQL parameter handling
+
+## References
+
+- MySQL LIMIT syntax: requires integer expressions, not string literals
+- Express req.query: all values are strings (parsed from URL query string)
+- Discovered during: MINISTRY-LMS PG-to-MySQL migration — meetings endpoint broke with LIMIT '20'
+- Fix applied in: `server/database/sql-compat.js` _parseTemplate method
+- Contributed from: ministry-lms