@thierrynakoa/fire-flow 10.0.0

package/skills-library/basics/git-commit-conventions.md

@@ -0,0 +1,106 @@
+# Skill: Git Commit Conventions
+
+**Category:** Basics
+**Difficulty:** Beginner
+**Applies to:** Every project
+
+---
+
+## The Problem
+
+Commit messages like `"fixed stuff"`, `"wip"`, or `"asdfgh"` tell future-you (and your teammates) nothing. When something breaks three months later, you can't figure out what changed or why.
+
+---
+
+## The Solution: Conventional Commits
+
+A simple format that makes your history readable and searchable.
+
+### Format
+
+```
+type(scope): short description
+
+optional longer explanation
+```
+
+### Types
+
+| Type | Use When |
+|------|---------|
+| `feat` | Adding a new feature |
+| `fix` | Fixing a bug |
+| `docs` | Updating documentation only |
+| `style` | Formatting, missing semicolons — no logic change |
+| `refactor` | Restructuring code without changing behavior |
+| `test` | Adding or fixing tests |
+| `chore` | Build tools, dependencies, config files |
+
+---
+
+## Examples
+
+```bash
+# Good
+git commit -m "feat(auth): add JWT login endpoint"
+git commit -m "fix(payments): handle declined card error correctly"
+git commit -m "docs: update README with install instructions"
+git commit -m "chore: upgrade express from 4.18 to 4.19"
+
+# Bad
+git commit -m "fixed it"
+git commit -m "update"
+git commit -m "wip"
+git commit -m "changes"
+```
+
+---
+
+## The 50/72 Rule
+
+- **Subject line:** 50 characters max. Use imperative mood — "add feature", not "added feature"
+- **Body:** 72 characters per line. Explain WHY, not what (the diff shows what)
+
+```bash
+git commit -m "fix(auth): prevent login with expired tokens
+
+JWT tokens were not being checked for expiration before
+granting access. Added expiry check in the middleware.
+Fixes #42."
+```
+
+---
+
+## Scope (Optional but Helpful)
+
+The scope is the part of the app you changed:
+
+```
+feat(auth): ...        # authentication system
+fix(api): ...          # API layer
+style(dashboard): ...  # dashboard UI
+chore(deps): ...       # dependencies
+```
+
+---
+
+## Practical Habits
+
+1. **Commit one thing at a time** — one commit = one logical change
+2. **Commit often** — small commits are easier to review and revert
+3. **Never commit broken code** — your main branch should always work
+4. **Write the message before you forget** — commit right after the change
+
+---
+
+## Check Your Last Commits
+
+```bash
+git log --oneline -10
+```
+
+If you can't tell what each commit did from the message alone, your messages need work.
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/basics/readme-template.md

@@ -0,0 +1,108 @@
+# Skill: README Template
+
+**Category:** Basics
+**Difficulty:** Beginner
+**Applies to:** Every project
+
+---
+
+## The Problem
+
+A project without a README is a project no one can use — including future you. A good README answers three questions in under 60 seconds: What is this? How do I install it? How do I use it?
+
+---
+
+## The Template
+
+Copy this and fill it in:
+
+```markdown
+# Project Name
+
+One sentence describing what this project does and who it is for.
+
+## Features
+
+- Feature one — what it does for the user
+- Feature two
+- Feature three
+
+## Requirements
+
+- Node.js 18+ (or Python 3.10+, etc.)
+- PostgreSQL 14+
+- An account at [ServiceName](https://example.com) (if needed)
+
+## Installation
+
+1. Clone the repo:
+   git clone https://github.com/your-username/your-project.git
+   cd your-project
+
+2. Install dependencies:
+   npm install
+
+3. Set up environment variables:
+   cp .env.example .env
+   # Edit .env with your values
+
+4. Set up the database:
+   npm run db:migrate
+
+5. Start the app:
+   npm run dev
+
+The app will be running at http://localhost:3000
+
+## Usage
+
+Describe the main thing a user does here. Include a screenshot if you can.
+
+### Example
+
+Show a code snippet or command that demonstrates the core feature:
+   curl http://localhost:3000/api/health
+   # Returns: {"status": "ok"}
+
+## Project Structure
+
+   src/
+   ├── routes/       # API endpoints
+   ├── models/       # Database models
+   ├── middleware/   # Auth, validation
+   └── utils/        # Helper functions
+
+## Running Tests
+
+   npm test
+
+## Deployment
+
+Brief notes on how to deploy (or link to a separate DEPLOYMENT.md).
+
+## License
+
+MIT License — see LICENSE file for details.
+```
+
+---
+
+## What Makes a README Great
+
+| Include | Skip |
+|---------|------|
+| Install steps that actually work | Your development diary |
+| What the project does in one sentence | Every minor feature listed |
+| A working example or screenshot | Apologies for bad code |
+| How to run tests | Future plans (put those in Issues) |
+| License | Obvious things ("this is a web app") |
+
+---
+
+## Quick Test
+
+After writing your README, ask someone who has never seen your project to install it using only the README. Every place they get stuck is a gap to fix.
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/common-tasks/async-await-patterns.md

@@ -0,0 +1,157 @@
+# Skill: Async/Await Patterns
+
+**Category:** Common Tasks
+**Difficulty:** Beginner–Intermediate
+**Applies to:** JavaScript, Node.js
+
+---
+
+## The Problem
+
+JavaScript is non-blocking — it doesn't wait for slow things (database calls, API calls, file reads) before moving to the next line. Without proper async handling, you get empty data, race conditions, and crashes that are hard to debug.
+
+---
+
+## The Evolution (Why Async/Await Exists)
+
+```js
+// 1. Callbacks — original approach, gets messy fast
+getUser(id, function(err, user) {
+  getPosts(user.id, function(err, posts) {
+    getComments(posts[0].id, function(err, comments) {
+      // "callback hell" — deeply nested, hard to read
+    });
+  });
+});
+
+// 2. Promises — better, but still chained
+getUser(id)
+  .then(user => getPosts(user.id))
+  .then(posts => getComments(posts[0].id))
+  .catch(err => console.error(err));
+
+// 3. Async/Await — reads like normal code
+async function loadData(id) {
+  const user = await getUser(id);
+  const posts = await getPosts(user.id);
+  const comments = await getComments(posts[0].id);
+  return comments;
+}
+```
+
+---
+
+## Pattern 1: Basic Async Function
+
+```js
+// Always use try/catch with await
+async function getUser(id) {
+  try {
+    const result = await db.query('SELECT * FROM users WHERE id = $1', [id]);
+    return result.rows[0];
+  } catch (err) {
+    console.error('getUser failed:', err.message);
+    throw err; // re-throw so the caller knows it failed
+  }
+}
+
+// Calling an async function
+const user = await getUser(42);
+```
+
+---
+
+## Pattern 2: Run Tasks in Parallel
+
+When tasks don't depend on each other, run them at the same time:
+
+```js
+// SLOW — runs one after the other (total: 3 seconds)
+const user = await fetchUser(id);       // 1 second
+const posts = await fetchPosts(id);     // 1 second
+const stats = await fetchStats(id);     // 1 second
+
+// FAST — runs all at once (total: ~1 second)
+const [user, posts, stats] = await Promise.all([
+  fetchUser(id),
+  fetchPosts(id),
+  fetchStats(id),
+]);
+```
+
+Use `Promise.all` whenever the tasks are independent. If one fails, the whole thing fails.
+
+---
+
+## Pattern 3: Run Tasks in Parallel, Handle Individual Failures
+
+```js
+// Promise.allSettled — each result tells you if it succeeded or failed
+const results = await Promise.allSettled([
+  fetchUser(id),
+  fetchPosts(id),
+  fetchStats(id),
+]);
+
+const [userResult, postsResult, statsResult] = results;
+
+if (userResult.status === 'fulfilled') {
+  console.log(userResult.value); // the data
+} else {
+  console.error(userResult.reason); // the error
+}
+```
+
+---
+
+## Pattern 4: Async in a Loop
+
+```js
+// WRONG — all start at once, order not guaranteed
+const userIds = [1, 2, 3];
+userIds.forEach(async (id) => {
+  const user = await getUser(id); // forEach doesn't await
+  console.log(user);
+});
+
+// CORRECT — sequential (one at a time)
+for (const id of userIds) {
+  const user = await getUser(id);
+  console.log(user);
+}
+
+// CORRECT — parallel (all at once, faster)
+const users = await Promise.all(userIds.map(id => getUser(id)));
+```
+
+---
+
+## Pattern 5: Timeout a Slow Request
+
+```js
+function withTimeout(promise, ms) {
+  const timeout = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error(`Timed out after ${ms}ms`)), ms)
+  );
+  return Promise.race([promise, timeout]);
+}
+
+// Usage
+const user = await withTimeout(fetchUser(id), 5000); // fail after 5 seconds
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| `await` outside an `async` function | Mark the function as `async` |
+| Forgetting `await` before a promise | Add `await` — you're reading the promise object, not the result |
+| Using `forEach` with `async` | Use `for...of` or `Promise.all` instead |
+| No `try/catch` around `await` | Wrap in try/catch or the error crashes the process |
+| Sequential awaits when parallel is fine | Use `Promise.all` for independent tasks |
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/common-tasks/auth-jwt-basics.md

@@ -0,0 +1,164 @@
+# Skill: JWT Authentication Basics
+
+**Category:** Common Tasks
+**Difficulty:** Beginner–Intermediate
+**Applies to:** Node.js/Express
+
+---
+
+## What is JWT?
+
+JWT (JSON Web Token) is a way to prove a user is logged in without checking the database on every request. When a user logs in, you give them a token. They send that token with every future request. You verify the token — no database lookup needed.
+
+A JWT looks like this:
+```
+eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOjQyfQ.sFlKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
+It has three parts separated by dots: Header . Payload . Signature
+
+---
+
+## Setup
+
+```bash
+npm install jsonwebtoken bcryptjs
+```
+
+```
+# .env
+JWT_SECRET=use-a-long-random-string-minimum-32-characters
+JWT_EXPIRES_IN=7d
+```
+
+---
+
+## Step 1 — Register (Create a User)
+
+```js
+const bcrypt = require('bcryptjs');
+
+router.post('/register', async (req, res) => {
+  const { name, email, password } = req.body;
+
+  if (!name || !email || !password)
+    return res.status(400).json({ error: 'All fields required' });
+
+  // Check if email already exists
+  const existing = await db.query('SELECT id FROM users WHERE email = $1', [email]);
+  if (existing.rows.length > 0)
+    return res.status(409).json({ error: 'Email already in use' });
+
+  // Hash the password — never store plain text
+  const hash = await bcrypt.hash(password, 12);
+
+  const result = await db.query(
+    'INSERT INTO users (name, email, password_hash) VALUES ($1, $2, $3) RETURNING id, name, email',
+    [name, email, hash]
+  );
+
+  res.status(201).json({ user: result.rows[0] });
+});
+```
+
+---
+
+## Step 2 — Login (Issue a Token)
+
+```js
+const jwt = require('jsonwebtoken');
+
+router.post('/login', async (req, res) => {
+  const { email, password } = req.body;
+
+  const result = await db.query('SELECT * FROM users WHERE email = $1', [email]);
+  const user = result.rows[0];
+
+  // Use a vague error — don't tell attacker which part was wrong
+  if (!user || !(await bcrypt.compare(password, user.password_hash)))
+    return res.status(401).json({ error: 'Invalid email or password' });
+
+  const token = jwt.sign(
+    { userId: user.id, email: user.email },
+    process.env.JWT_SECRET,
+    { expiresIn: process.env.JWT_EXPIRES_IN }
+  );
+
+  res.json({ token, user: { id: user.id, name: user.name, email: user.email } });
+});
+```
+
+---
+
+## Step 3 — Auth Middleware (Protect Routes)
+
+```js
+// middleware/auth.js
+const jwt = require('jsonwebtoken');
+
+function requireAuth(req, res, next) {
+  const header = req.headers.authorization;
+  if (!header || !header.startsWith('Bearer '))
+    return res.status(401).json({ error: 'No token provided' });
+
+  const token = header.split(' ')[1];
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded; // now available in route as req.user
+    next();
+  } catch (err) {
+    return res.status(401).json({ error: 'Token invalid or expired' });
+  }
+}
+
+module.exports = requireAuth;
+```
+
+---
+
+## Step 4 — Protect a Route
+
+```js
+const requireAuth = require('../middleware/auth');
+
+// Public route — anyone can access
+router.get('/public', (req, res) => res.json({ message: 'Hello world' }));
+
+// Protected route — must be logged in
+router.get('/profile', requireAuth, async (req, res) => {
+  const user = await db.query('SELECT id, name, email FROM users WHERE id = $1', [req.user.userId]);
+  res.json(user.rows[0]);
+});
+```
+
+---
+
+## Step 5 — Frontend: Sending the Token
+
+```js
+// Save token after login
+localStorage.setItem('token', data.token);
+
+// Send token with every protected request
+const response = await fetch('/api/profile', {
+  headers: {
+    'Authorization': `Bearer ${localStorage.getItem('token')}`
+  }
+});
+```
+
+---
+
+## Security Rules
+
+| Do | Don't |
+|----|-------|
+| Use a long random JWT_SECRET | Use a short or guessable secret |
+| Hash passwords with bcrypt (cost 10–14) | Store plain text or MD5 passwords |
+| Give vague login error messages | Say "wrong password" vs "wrong email" |
+| Set token expiry (7d or less) | Create tokens that never expire |
+| Use HTTPS in production | Send tokens over plain HTTP |
+
+---
+
+*Fire Flow Skills Library — MIT License*

package/skills-library/common-tasks/database-schema-design.md

@@ -0,0 +1,166 @@
+# Skill: Database Schema Design
+
+**Category:** Common Tasks
+**Difficulty:** Beginner–Intermediate
+**Applies to:** PostgreSQL, MySQL, SQLite
+
+---
+
+## The Problem
+
+A poorly designed schema causes bugs that are painful to fix later — duplicate data, broken relationships, impossible queries. Getting it right at the start saves enormous time.
+
+---
+
+## The Core Rules
+
+### 1. Every table needs a primary key
+
+```sql
+-- Every row needs a unique identifier
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,  -- auto-incrementing integer
+  -- or use UUID:
+  -- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name VARCHAR(100) NOT NULL,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 2. Use foreign keys to link tables
+
+```sql
+-- posts belong to users
+CREATE TABLE posts (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  title VARCHAR(255) NOT NULL,
+  body TEXT,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+`ON DELETE CASCADE` means: if the user is deleted, delete their posts too.
+`ON DELETE RESTRICT` means: refuse to delete a user who has posts.
+
+### 3. Don't repeat data — normalize it
+
+```sql
+-- BAD: storing category name in every post (repeats data, hard to rename)
+posts: id | title | category_name
+
+-- GOOD: categories in their own table
+CREATE TABLE categories (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(100) UNIQUE NOT NULL
+);
+
+CREATE TABLE posts (
+  id SERIAL PRIMARY KEY,
+  title VARCHAR(255) NOT NULL,
+  category_id INTEGER REFERENCES categories(id)
+);
+```
+
+### 4. Many-to-Many relationships need a join table
+
+```sql
+-- A post can have many tags. A tag can be on many posts.
+
+CREATE TABLE tags (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(50) UNIQUE NOT NULL
+);
+
+CREATE TABLE post_tags (
+  post_id INTEGER REFERENCES posts(id) ON DELETE CASCADE,
+  tag_id INTEGER REFERENCES tags(id) ON DELETE CASCADE,
+  PRIMARY KEY (post_id, tag_id)  -- prevents duplicates
+);
+```
+
+---
+
+## Column Types Cheat Sheet
+
+| Type | Use For |
+|------|---------|
+| `SERIAL` / `INTEGER` | Auto-increment IDs, counts |
+| `UUID` | IDs when you don't want guessable numbers |
+| `VARCHAR(n)` | Short text with a max length |
+| `TEXT` | Long text, no length limit |
+| `BOOLEAN` | True/false flags |
+| `INTEGER` | Whole numbers |
+| `DECIMAL(10,2)` | Money (never use FLOAT for money) |
+| `TIMESTAMP` | Date + time |
+| `DATE` | Date only |
+| `JSONB` | Flexible data (PostgreSQL only) |
+
+---
+
+## A Complete Example
+
+```sql
+-- Users
+CREATE TABLE users (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(100) NOT NULL,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash VARCHAR(255) NOT NULL,
+  role VARCHAR(20) DEFAULT 'user' CHECK (role IN ('user', 'admin')),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Products
+CREATE TABLE products (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  price DECIMAL(10,2) NOT NULL CHECK (price >= 0),
+  stock_count INTEGER DEFAULT 0 CHECK (stock_count >= 0),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Orders
+CREATE TABLE orders (
+  id SERIAL PRIMARY KEY,
+  user_id INTEGER NOT NULL REFERENCES users(id),
+  total DECIMAL(10,2) NOT NULL,
+  status VARCHAR(20) DEFAULT 'pending' CHECK (status IN ('pending', 'paid', 'shipped', 'cancelled')),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Order line items
+CREATE TABLE order_items (
+  id SERIAL PRIMARY KEY,
+  order_id INTEGER NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
+  product_id INTEGER NOT NULL REFERENCES products(id),
+  quantity INTEGER NOT NULL CHECK (quantity > 0),
+  price_at_purchase DECIMAL(10,2) NOT NULL  -- snapshot price, not live price
+);
+```
+
+---
+
+## Indexes — Speed Up Queries
+
+```sql
+-- Add indexes on columns you frequently search or filter by
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_users_email ON users(email);  -- usually covered by UNIQUE
+```
+
+---
+
+## Questions to Ask Before Creating a Table
+
+1. What is the primary key?
+2. What other tables does this relate to?
+3. What columns should be NOT NULL?
+4. What columns need to be UNIQUE?
+5. What should happen when a related record is deleted?
+
+---
+
+*Fire Flow Skills Library — MIT License*