@thierrynakoa/fire-flow 10.0.0

package/skills-library/quality-safety/debugging-steps.md

@@ -0,0 +1,147 @@
+# Skill: Debugging Steps
+
+**Category:** Quality & Safety
+**Difficulty:** Beginner
+**Applies to:** Every project
+
+---
+
+## The Problem
+
+Most developers debug by guessing — changing random things until it works. This wastes hours and often introduces new bugs. Systematic debugging finds the problem in minutes.
+
+---
+
+## The 5-Step Method
+
+### Step 1 — Read the Error Message
+
+The error message tells you exactly what went wrong. Read the whole thing, including the stack trace.
+
+```
+TypeError: Cannot read properties of undefined (reading 'email')
+    at getUserEmail (routes/users.js:24:23)
+    at router.get (/routes/users.js:18:20)
+```
+
+This tells you:
+- **What:** Trying to read `.email` from something that is `undefined`
+- **Where:** `routes/users.js` line 24
+- **How it got there:** Called from line 18
+
+Go to line 24. `user` is `undefined` — the database returned no rows.
+
+---
+
+### Step 2 — Reproduce it Reliably
+
+Before fixing, make sure you can make the bug happen on purpose.
+
+- What exact steps trigger it?
+- Does it happen every time, or randomly?
+- Does it happen in development but not production (or vice versa)?
+
+A bug you can reproduce consistently is a bug you can fix.
+
+---
+
+### Step 3 — Isolate Where It Breaks
+
+Narrow down where in the code the problem starts. Use `console.log` to trace values:
+
+```js
+router.get('/users/:id', async (req, res) => {
+  console.log('1. Request received, id:', req.params.id);
+
+  const result = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);
+  console.log('2. DB result:', result.rows);
+
+  const user = result.rows[0];
+  console.log('3. User:', user); // if undefined, the query returned nothing
+
+  res.json({ email: user.email }); // crashes if user is undefined
+});
+```
+
+Work from the outside in. Log at the start, then in the middle, then closer to the crash until you find where the data goes wrong.
+
+---
+
+### Step 4 — Form a Hypothesis and Test It
+
+Once you know where, make a specific prediction about why:
+
+> "I think the user query returns nothing because the ID from the URL is a string, but the database expects an integer."
+
+Test it:
+```js
+console.log(typeof req.params.id); // 'string' — confirmed!
+// Fix: parseInt(req.params.id, 10)
+```
+
+If your hypothesis is wrong, form a new one. Don't just try random fixes.
+
+---
+
+### Step 5 — Fix, Verify, and Clean Up
+
+- Make the smallest change that fixes the problem
+- Verify the original bug is gone
+- Check that nothing else broke
+- Remove all the `console.log` statements you added
+- Write a test so it can't come back silently
+
+---
+
+## Common Bug Patterns and Their Fixes
+
+| Symptom | Likely Cause | How to Check |
+|---------|-------------|--------------|
+| `undefined` where you expect an object | Database returned 0 rows | Log the query result |
+| `Cannot read property of null` | Accessing a property before data loads | Check for null before accessing |
+| Fetch returns HTML instead of JSON | API route not found (404) | Check the URL and router setup |
+| Changes not showing up | Old code cached / wrong file edited | Hard refresh, check file path |
+| Works locally, breaks in production | Missing env variable | Check production env config |
+| CORS error in browser | Backend not allowing your frontend origin | Check CORS middleware |
+| `jwt malformed` | Token corrupted or wrong format | Log the raw Authorization header |
+
+---
+
+## The Console is Your Friend
+
+```js
+// Log an object clearly
+console.log('user:', JSON.stringify(user, null, 2));
+
+// Log with a timestamp
+console.log(new Date().toISOString(), 'step reached');
+
+// Log type and value
+console.log('id type:', typeof id, 'value:', id);
+
+// Trace where a function is called from
+console.trace('Called from:');
+```
+
+---
+
+## When You've Been Stuck for 20 Minutes
+
+1. **Explain the problem out loud** (rubber duck debugging) — saying it out loud often reveals the answer
+2. **Take a 10-minute break** — your brain keeps working
+3. **Search the exact error message** in quotes on Google or Stack Overflow
+4. **Read the documentation** for the library you're using — check if your usage matches the examples
+5. **Ask for help** — share the error, the code, and what you've already tried
+
+---
+
+## What Not to Do
+
+- Don't comment out code randomly hoping the bug disappears
+- Don't change multiple things at once — you won't know what fixed it
+- Don't ignore warnings in the console — they often point to the real problem
+- Don't assume the library is broken — it's almost always your code
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/quality-safety/deployment-checklist.md

@@ -0,0 +1,155 @@
+# Skill: Deployment Checklist
+
+**Category:** Quality & Safety
+**Difficulty:** Beginner
+**Applies to:** Every web project going to production
+
+---
+
+## Before You Deploy — Run Through This List
+
+Going live with something broken is worse than not going live at all. This checklist catches the most common deployment failures.
+
+---
+
+## 1. Environment & Secrets
+
+- [ ] All secrets are in production environment variables (not in code)
+- [ ] `NODE_ENV=production` is set
+- [ ] Database URL points to the **production** database, not localhost
+- [ ] JWT secret in production is different from your development secret
+- [ ] No `.env` file is committed to git
+- [ ] All required env variables are documented in `.env.example`
+
+**How to verify:**
+```bash
+# List your production env vars (on Railway, Render, etc.)
+# Or test locally with production values:
+NODE_ENV=production node -e "console.log(process.env.DATABASE_URL)"
+```
+
+---
+
+## 2. Database
+
+- [ ] All migrations have been run on the production database
+- [ ] Production database has been backed up before this deployment
+- [ ] Seed data (categories, default settings) is in place if needed
+- [ ] Database indexes exist on frequently queried columns
+- [ ] Connection pooling is configured for production load
+
+```bash
+# Run migrations
+npm run db:migrate
+
+# Verify tables exist
+psql $DATABASE_URL -c "\dt"
+```
+
+---
+
+## 3. Code Quality
+
+- [ ] All tests pass
+- [ ] No `console.log` debug statements left in production code
+- [ ] No hardcoded localhost URLs — use env variables for all service URLs
+- [ ] Error handling is in place for all API routes
+- [ ] `npm audit` shows no critical vulnerabilities
+
+```bash
+npm test
+npm audit
+grep -r "localhost" src/ --include="*.js" | grep -v ".env"
+```
+
+---
+
+## 4. Security
+
+- [ ] HTTPS is enabled (SSL certificate is valid)
+- [ ] CORS is restricted to your production frontend domain
+- [ ] Rate limiting is in place on auth endpoints
+- [ ] Sensitive routes require authentication
+- [ ] File uploads are validated and size-limited
+
+---
+
+## 5. Performance
+
+- [ ] Images are compressed and sized appropriately
+- [ ] Frontend assets are minified and bundled (run `npm run build`)
+- [ ] Database queries use indexes where needed
+- [ ] Caching is in place for data that doesn't change often (if applicable)
+
+---
+
+## 6. Frontend Build
+
+- [ ] Production build completed without errors (`npm run build`)
+- [ ] Build output points to production API URL, not localhost
+- [ ] 404 page exists and looks professional
+- [ ] Favicon is set
+- [ ] Page titles are set correctly (`<title>App Name</title>`)
+
+---
+
+## 7. Monitoring
+
+- [ ] Error logging is in place (console.error at minimum)
+- [ ] You know how to view production logs
+- [ ] You have a way to be alerted if the app goes down
+
+**Simple health check endpoint:**
+```js
+app.get('/api/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+```
+
+Set up an uptime monitor at [uptimerobot.com](https://uptimerobot.com) (free) to ping this every 5 minutes.
+
+---
+
+## 8. Post-Deployment Smoke Test
+
+After deploying, manually test these in the browser:
+
+- [ ] Home page loads
+- [ ] User can register
+- [ ] User can log in
+- [ ] Core feature works end-to-end
+- [ ] Logout works
+- [ ] No JavaScript errors in browser console (press F12)
+
+---
+
+## Rollback Plan
+
+Before every deployment, know how to roll back:
+
+```bash
+# Git: revert to previous commit
+git revert HEAD
+git push origin main
+
+# Or: deploy the previous version manually
+git checkout <previous-commit-hash>
+git push origin main --force
+```
+
+If you changed the database schema, have a down migration ready.
+
+---
+
+## Deployment Platforms (Beginner-Friendly)
+
+| Platform | Best For | Free Tier |
+|----------|---------|-----------|
+| [Railway](https://railway.app) | Node.js + PostgreSQL together | Yes |
+| [Render](https://render.com) | Web services + databases | Yes (sleeps after inactivity) |
+| [Vercel](https://vercel.com) | Frontend + serverless functions | Yes |
+| [Fly.io](https://fly.io) | Dockerized apps | Yes |
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/quality-safety/security-checklist.md

@@ -0,0 +1,204 @@
+# Skill: Security Checklist
+
+**Category:** Quality & Safety
+**Difficulty:** Beginner
+**Applies to:** Every web project
+
+---
+
+## The 10 Most Common Security Mistakes
+
+Based on the OWASP Top 10 — the industry-standard list of web vulnerabilities.
+
+---
+
+### 1. SQL Injection
+
+**What it is:** An attacker puts SQL code in your input fields to steal or destroy your data.
+
+```js
+// VULNERABLE — never do this
+const query = `SELECT * FROM users WHERE email = '${req.body.email}'`;
+// Attacker sends: ' OR '1'='1 — returns ALL users
+
+// SAFE — always use parameterized queries
+const result = await db.query('SELECT * FROM users WHERE email = $1', [req.body.email]);
+```
+
+**Rule:** Never build SQL strings by concatenating user input.
+
+---
+
+### 2. Hardcoded Secrets
+
+**What it is:** API keys, passwords, or tokens written directly in code and committed to git.
+
+```js
+// WRONG
+const stripe = require('stripe')('sk_live_abc123realkey');
+
+// RIGHT
+const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
+```
+
+**Rule:** Every secret lives in `.env`. `.env` is in `.gitignore`. See [env-variables.md](../basics/env-variables.md).
+
+---
+
+### 3. Missing Authentication on Routes
+
+**What it is:** Forgetting to protect routes that should require login.
+
+```js
+// WRONG — anyone can delete any user
+router.delete('/users/:id', async (req, res) => { ... });
+
+// RIGHT
+router.delete('/users/:id', requireAuth, async (req, res) => { ... });
+```
+
+**Rule:** Every route that reads private data or makes changes must have auth middleware.
+
+---
+
+### 4. Plain Text Passwords
+
+**What it is:** Storing user passwords as plain text in the database. One breach = all accounts compromised.
+
+```js
+// WRONG
+await db.query('INSERT INTO users (password) VALUES ($1)', [password]);
+
+// RIGHT — always hash with bcrypt
+const hash = await bcrypt.hash(password, 12);
+await db.query('INSERT INTO users (password_hash) VALUES ($1)', [hash]);
+```
+
+**Rule:** Never store, log, or transmit plain text passwords. Hash with bcrypt.
+
+---
+
+### 5. No Input Validation
+
+**What it is:** Trusting whatever the user sends without checking it.
+
+```js
+// WRONG — user could send a negative price, or a 10MB JSON body
+app.post('/products', async (req, res) => {
+  await db.query('INSERT INTO products (price) VALUES ($1)', [req.body.price]);
+});
+
+// RIGHT
+app.use(express.json({ limit: '10kb' })); // limit body size
+app.post('/products', async (req, res) => {
+  const price = parseFloat(req.body.price);
+  if (isNaN(price) || price < 0) return res.status(400).json({ error: 'Invalid price' });
+  await db.query('INSERT INTO products (price) VALUES ($1)', [price]);
+});
+```
+
+**Rule:** Validate every input on the server. See [form-validation.md](../common-tasks/form-validation.md).
+
+---
+
+### 6. Exposing Error Details to Users
+
+**What it is:** Sending stack traces or database errors to the frontend, exposing your internal structure.
+
+```js
+// WRONG
+res.status(500).json({ error: err.stack }); // shows file paths, table names
+
+// RIGHT
+console.error(err); // log full error on server
+res.status(500).json({ error: 'Something went wrong. Please try again.' });
+```
+
+**Rule:** Log errors on the server. Send only generic messages to the client.
+
+---
+
+### 7. Missing HTTPS
+
+**What it is:** Sending data over HTTP allows anyone on the network to read it (passwords, tokens, everything).
+
+**Rule:** Always use HTTPS in production. Most hosting providers (Vercel, Railway, Render) do this automatically. For VPS, use Let's Encrypt (free SSL) via Certbot.
+
+---
+
+### 8. CORS Misconfiguration
+
+**What it is:** Allowing any website to call your API.
+
+```js
+// WRONG — allows any origin
+app.use(cors());
+
+// RIGHT — only allow your own frontend
+app.use(cors({
+  origin: process.env.FRONTEND_URL, // e.g. 'https://myapp.com'
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+}));
+```
+
+**Rule:** Set CORS to your specific frontend domain in production.
+
+---
+
+### 9. Broken Access Control
+
+**What it is:** A logged-in user can access or edit another user's data.
+
+```js
+// WRONG — user can request any profile by changing the ID
+router.get('/profile/:id', requireAuth, async (req, res) => {
+  const user = await db.query('SELECT * FROM users WHERE id = $1', [req.params.id]);
+  res.json(user.rows[0]);
+});
+
+// RIGHT — only return the logged-in user's own data
+router.get('/profile', requireAuth, async (req, res) => {
+  const user = await db.query('SELECT * FROM users WHERE id = $1', [req.user.userId]);
+  res.json(user.rows[0]);
+});
+```
+
+**Rule:** When fetching user-specific data, always filter by the authenticated user's ID from the token — not from the URL.
+
+---
+
+### 10. Outdated Dependencies
+
+**What it is:** Old packages often have known security vulnerabilities.
+
+```bash
+# Check for vulnerabilities
+npm audit
+
+# Fix automatically (safe fixes only)
+npm audit fix
+
+# See outdated packages
+npm outdated
+```
+
+**Rule:** Run `npm audit` before every deployment. Update dependencies regularly.
+
+---
+
+## Quick Pre-Launch Checklist
+
+- [ ] All secrets are in `.env`, not in code
+- [ ] `.env` is in `.gitignore`
+- [ ] All write routes require authentication
+- [ ] Passwords are hashed with bcrypt
+- [ ] All user input is validated on the server
+- [ ] CORS is set to the production frontend domain
+- [ ] HTTPS is enabled
+- [ ] `npm audit` shows no critical vulnerabilities
+- [ ] Error messages sent to users contain no internal details
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/quality-safety/testing-basics.md

@@ -0,0 +1,180 @@
+# Skill: Testing Basics
+
+**Category:** Quality & Safety
+**Difficulty:** Beginner
+**Applies to:** Node.js (Jest), any language
+
+---
+
+## Why Test?
+
+Tests catch bugs before your users do. They also let you change code confidently — if the tests still pass, you didn't break anything. Untested code is code you're afraid to touch.
+
+---
+
+## Setup (Jest)
+
+```bash
+npm install --save-dev jest
+```
+
+```json
+// package.json
+{
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch"
+  }
+}
+```
+
+---
+
+## What to Test
+
+**Test these:**
+- Functions that calculate or transform data
+- API endpoints (correct response, correct status code)
+- Edge cases — what happens with empty input, null, zero, very large numbers
+- Error paths — what happens when the database is down, or input is invalid
+
+**Don't bother testing:**
+- Third-party libraries (they have their own tests)
+- Simple getters/setters with no logic
+- Things that are just passing data through unchanged
+
+---
+
+## Pattern 1: Unit Test (Pure Function)
+
+A unit test tests one function in isolation:
+
+```js
+// utils/price.js
+function applyDiscount(price, discountPercent) {
+  if (price < 0) throw new Error('Price cannot be negative');
+  if (discountPercent < 0 || discountPercent > 100) throw new Error('Invalid discount');
+  return price * (1 - discountPercent / 100);
+}
+
+module.exports = { applyDiscount };
+```
+
+```js
+// utils/price.test.js
+const { applyDiscount } = require('./price');
+
+describe('applyDiscount', () => {
+  test('applies 10% discount correctly', () => {
+    expect(applyDiscount(100, 10)).toBe(90);
+  });
+
+  test('applies 0% discount (no change)', () => {
+    expect(applyDiscount(100, 0)).toBe(100);
+  });
+
+  test('applies 100% discount (free)', () => {
+    expect(applyDiscount(100, 100)).toBe(0);
+  });
+
+  test('throws on negative price', () => {
+    expect(() => applyDiscount(-10, 10)).toThrow('Price cannot be negative');
+  });
+
+  test('throws on invalid discount over 100', () => {
+    expect(() => applyDiscount(100, 110)).toThrow('Invalid discount');
+  });
+});
+```
+
+Run: `npm test`
+
+---
+
+## Pattern 2: API Test (Integration Test)
+
+Test your actual routes with real HTTP requests:
+
+```bash
+npm install --save-dev supertest
+```
+
+```js
+// routes/users.test.js
+const request = require('supertest');
+const app = require('../app');
+
+describe('GET /api/users/:id', () => {
+  test('returns 200 and user for valid id', async () => {
+    const res = await request(app).get('/api/users/1');
+    expect(res.status).toBe(200);
+    expect(res.body).toHaveProperty('email');
+  });
+
+  test('returns 404 for non-existent user', async () => {
+    const res = await request(app).get('/api/users/99999');
+    expect(res.status).toBe(404);
+    expect(res.body).toHaveProperty('error');
+  });
+});
+
+describe('POST /api/users', () => {
+  test('returns 400 when email is missing', async () => {
+    const res = await request(app)
+      .post('/api/users')
+      .send({ name: 'Jane' }); // no email
+    expect(res.status).toBe(400);
+  });
+});
+```
+
+---
+
+## The AAA Pattern
+
+Every test follows this structure:
+
+```js
+test('description of what should happen', () => {
+  // Arrange — set up the data
+  const price = 100;
+  const discount = 20;
+
+  // Act — run the thing being tested
+  const result = applyDiscount(price, discount);
+
+  // Assert — verify the result
+  expect(result).toBe(80);
+});
+```
+
+---
+
+## Most Useful Jest Matchers
+
+```js
+expect(value).toBe(42)              // strict equality (===)
+expect(value).toEqual({ a: 1 })     // deep equality for objects
+expect(value).toBeTruthy()          // any truthy value
+expect(value).toBeNull()
+expect(value).toBeGreaterThan(0)
+expect(array).toHaveLength(3)
+expect(object).toHaveProperty('name')
+expect(string).toContain('hello')
+expect(fn).toThrow('message')
+```
+
+---
+
+## Aim for This Coverage
+
+| Layer | What to Test |
+|-------|-------------|
+| Utility functions | All branches, all edge cases |
+| API endpoints | Happy path + main error cases |
+| Auth middleware | Blocked with no token, blocked with bad token, passes with good token |
+| Database queries | At least the shape of the returned data |
+
+---
+
+*Fire Flow Skills Library — MIT License*