@hivehub/rulebook 1.2.0

package/templates/services/SQLITE.md

@@ -0,0 +1,294 @@
+<!-- SQLITE:START -->
+# SQLite Database Instructions
+
+**CRITICAL**: Use SQLite for embedded databases, local storage, development, and small-scale applications with zero configuration.
+
+## Core Features
+
+### Connection
+```typescript
+// Using better-sqlite3 (synchronous, faster)
+import Database from 'better-sqlite3'
+
+const db = new Database(process.env.DB_PATH || './database.db', {
+  verbose: process.env.NODE_ENV === 'development' ? console.log : undefined,
+})
+
+// Using sqlite3 (asynchronous)
+import sqlite3 from 'sqlite3'
+
+const db = new sqlite3.Database(process.env.DB_PATH || './database.db', (err) => {
+  if (err) {
+    console.error('Error opening database', err)
+  }
+})
+
+// Using better-sqlite3 with WAL mode (recommended)
+const db = new Database('./database.db')
+db.pragma('journal_mode = WAL') // Write-Ahead Logging
+db.pragma('foreign_keys = ON')  // Enable foreign keys
+```
+
+### Basic Queries
+```typescript
+// Using better-sqlite3 (synchronous)
+// SELECT
+const stmt = db.prepare('SELECT * FROM users WHERE id = ?')
+const user = stmt.get(userId)
+
+// INSERT
+const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
+const info = insert.run('John Doe', 'john@example.com')
+const newId = info.lastInsertRowid
+
+// UPDATE
+const update = db.prepare('UPDATE users SET name = ? WHERE id = ?')
+update.run('Jane Doe', userId)
+
+// DELETE
+const del = db.prepare('DELETE FROM users WHERE id = ?')
+del.run(userId)
+
+// Using sqlite3 (asynchronous)
+db.get('SELECT * FROM users WHERE id = ?', [userId], (err, row) => {
+  if (err) throw err
+  console.log(row)
+})
+
+db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John Doe', 'john@example.com'], function(err) {
+  if (err) throw err
+  console.log('Inserted with ID:', this.lastID)
+})
+```
+
+### Transactions
+```typescript
+// Using better-sqlite3
+const insertUser = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
+const insertPost = db.prepare('INSERT INTO posts (user_id, title) VALUES (?, ?)')
+
+const insertUserAndPost = db.transaction((userName, userEmail, postTitle) => {
+  const userInfo = insertUser.run(userName, userEmail)
+  const userId = userInfo.lastInsertRowid
+  insertPost.run(userId, postTitle)
+  return userId
+})
+
+const userId = insertUserAndPost('John Doe', 'john@example.com', 'First Post')
+
+// Using sqlite3
+db.serialize(() => {
+  db.run('BEGIN TRANSACTION')
+  db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com'], function(err) {
+    if (err) {
+      db.run('ROLLBACK')
+      throw err
+    }
+    const userId = this.lastID
+    db.run('INSERT INTO posts (user_id, title) VALUES (?, ?)', [userId, 'Post'], (err) => {
+      if (err) {
+        db.run('ROLLBACK')
+        throw err
+      }
+      db.run('COMMIT')
+    })
+  })
+})
+```
+
+### Advanced Features
+```typescript
+// JSON operations (SQLite 3.38+)
+const result = db.prepare(`
+  SELECT 
+    id,
+    name,
+    json_extract(metadata, '$.category') AS category
+  FROM products
+  WHERE json_extract(metadata, '$.category') = ?
+`).get('electronics')
+
+// Full-text search (FTS5)
+db.exec(`
+  CREATE VIRTUAL TABLE articles_fts USING fts5(
+    title,
+    content,
+    content_rowid=id
+  )
+`)
+
+const results = db.prepare(`
+  SELECT * FROM articles_fts
+  WHERE articles_fts MATCH ?
+`).all('search term')
+
+// Window functions (SQLite 3.25+)
+const result = db.prepare(`
+  SELECT 
+    name,
+    salary,
+    ROW_NUMBER() OVER (PARTITION BY department_id ORDER BY salary DESC) AS rank
+  FROM employees
+`).all()
+```
+
+## Common Patterns
+
+### Prepared Statements
+```typescript
+// Reuse prepared statements for better performance
+const getUserById = db.prepare('SELECT * FROM users WHERE id = ?')
+const getUserByEmail = db.prepare('SELECT * FROM users WHERE email = ?')
+
+// Use in functions
+function getUser(id: number) {
+  return getUserById.get(id)
+}
+
+function findUserByEmail(email: string) {
+  return getUserByEmail.get(email)
+}
+```
+
+### Batch Operations
+```typescript
+// Insert multiple rows efficiently
+const insert = db.prepare('INSERT INTO users (name, email) VALUES (?, ?)')
+const insertMany = db.transaction((users) => {
+  for (const user of users) {
+    insert.run(user.name, user.email)
+  }
+})
+
+insertMany([
+  { name: 'User 1', email: 'user1@example.com' },
+  { name: 'User 2', email: 'user2@example.com' },
+])
+```
+
+### Migrations
+```typescript
+// Simple migration system
+const migrations = [
+  `CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )`,
+  `CREATE TABLE IF NOT EXISTS posts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    title TEXT NOT NULL,
+    content TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id)
+  )`,
+]
+
+db.exec('BEGIN TRANSACTION')
+try {
+  for (const migration of migrations) {
+    db.exec(migration)
+  }
+  db.exec('COMMIT')
+} catch (error) {
+  db.exec('ROLLBACK')
+  throw error
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use WAL mode for better concurrency
+- Enable foreign keys
+- Use prepared statements
+- Use transactions for multiple operations
+- Create indexes on frequently queried columns
+- Use appropriate data types (TEXT, INTEGER, REAL, BLOB)
+- Backup database regularly
+- Use connection pooling (better-sqlite3 handles this)
+- Monitor database size
+- Use VACUUM periodically
+
+❌ **DON'T:**
+- Use for high-concurrency write scenarios
+- Store large binary data (use external storage)
+- Skip error handling
+- Use string concatenation for queries
+- Ignore database size limits
+- Skip indexes on foreign keys
+- Hardcode database paths
+- Ignore transaction boundaries
+- Use synchronous operations in async contexts (better-sqlite3 is fine)
+- Skip backups
+
+## Configuration
+
+### Environment Variables
+```bash
+DB_PATH=./database.db
+DB_PATH=/var/lib/myapp/database.db
+```
+
+### Initialization
+```typescript
+// Initialize database with schema
+const db = new Database('./database.db')
+
+db.pragma('journal_mode = WAL')
+db.pragma('foreign_keys = ON')
+db.pragma('synchronous = NORMAL')
+db.pragma('cache_size = 10000')
+db.pragma('temp_store = MEMORY')
+
+// Create tables
+db.exec(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  )
+  
+  CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)
+`)
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use in-memory database for tests
+const testDb = new Database(':memory:')
+
+// Or use separate test database
+const testDb = new Database('./test.db')
+
+// Clean up after tests
+afterEach(() => {
+  testDb.exec('DELETE FROM users')
+  testDb.exec('DELETE FROM posts')
+})
+
+afterAll(() => {
+  testDb.close()
+  // Optionally delete test database file
+})
+```
+
+### Health Checks
+```typescript
+function checkDatabaseHealth(): boolean {
+  try {
+    db.prepare('SELECT 1').get()
+    return true
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- SQLITE:END -->
+

package/templates/services/SQLSERVER.md

@@ -0,0 +1,294 @@
+<!-- SQLSERVER:START -->
+# SQL Server Database Instructions
+
+**CRITICAL**: Use SQL Server for enterprise relational data storage with advanced features, high availability, and Windows integration.
+
+## Core Features
+
+### Connection
+```typescript
+// Using mssql (Node.js)
+import sql from 'mssql'
+
+const pool = await sql.connect({
+  server: process.env.DB_HOST || 'localhost',
+  port: parseInt(process.env.DB_PORT || '1433'),
+  database: process.env.DB_NAME || 'myapp',
+  user: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  options: {
+    encrypt: process.env.NODE_ENV === 'production',
+    trustServerCertificate: process.env.NODE_ENV !== 'production',
+    enableArithAbort: true,
+    connectionTimeout: 30000,
+    requestTimeout: 30000,
+  },
+  pool: {
+    max: 10,
+    min: 0,
+    idleTimeoutMillis: 30000,
+  },
+})
+
+// Using tedious (lower level)
+import { Connection } from 'tedious'
+
+const connection = new Connection({
+  server: process.env.DB_HOST || 'localhost',
+  authentication: {
+    type: 'default',
+    options: {
+      userName: process.env.DB_USER,
+      password: process.env.DB_PASSWORD,
+    },
+  },
+  options: {
+    encrypt: true,
+    database: process.env.DB_NAME,
+    trustServerCertificate: true,
+  },
+})
+```
+
+### Basic Queries
+```typescript
+// SELECT
+const result = await pool.request()
+  .input('userId', sql.Int, userId)
+  .query('SELECT * FROM Users WHERE Id = @userId')
+const users = result.recordset
+
+// INSERT
+const result = await pool.request()
+  .input('name', sql.NVarChar, 'John Doe')
+  .input('email', sql.NVarChar, 'john@example.com')
+  .query('INSERT INTO Users (Name, Email) OUTPUT INSERTED.* VALUES (@name, @email)')
+const newUser = result.recordset[0]
+
+// UPDATE
+const result = await pool.request()
+  .input('id', sql.Int, userId)
+  .input('name', sql.NVarChar, 'Jane Doe')
+  .query('UPDATE Users SET Name = @name WHERE Id = @id')
+
+// DELETE
+await pool.request()
+  .input('id', sql.Int, userId)
+  .query('DELETE FROM Users WHERE Id = @id')
+```
+
+### Transactions
+```typescript
+const transaction = new sql.Transaction(pool)
+
+try {
+  await transaction.begin()
+  
+  const request = new sql.Request(transaction)
+  await request
+    .input('userId', sql.Int, userId)
+    .input('amount', sql.Decimal(18, 2), 1000)
+    .query('INSERT INTO Accounts (UserId, Balance) VALUES (@userId, @amount)')
+  
+  await request
+    .input('accountId', sql.Int, accountId)
+    .input('amount', sql.Decimal(18, 2), 1000)
+    .query('INSERT INTO Transactions (AccountId, Amount) VALUES (@accountId, @amount)')
+  
+  await transaction.commit()
+} catch (error) {
+  await transaction.rollback()
+  throw error
+}
+```
+
+### Advanced Features
+```typescript
+// Stored procedures
+const result = await pool.request()
+  .input('userId', sql.Int, userId)
+  .execute('sp_GetUserDetails')
+
+// JSON operations (SQL Server 2016+)
+const result = await pool.request()
+  .query(`
+    SELECT 
+      Id,
+      Name,
+      JSON_VALUE(Metadata, '$.category') AS Category
+    FROM Products
+    WHERE JSON_VALUE(Metadata, '$.category') = 'electronics'
+  `)
+
+// Full-text search
+const result = await pool.request()
+  .input('searchTerm', sql.NVarChar, 'search term')
+  .query(`
+    SELECT * FROM Articles
+    WHERE CONTAINS(Content, @searchTerm)
+  `)
+
+// Window functions
+const result = await pool.request()
+  .query(`
+    SELECT 
+      Name,
+      Salary,
+      ROW_NUMBER() OVER (PARTITION BY DepartmentId ORDER BY Salary DESC) AS Rank
+    FROM Employees
+  `)
+```
+
+## Common Patterns
+
+### Connection Pooling
+```typescript
+let pool: sql.ConnectionPool | null = null
+
+export async function getPool(): Promise<sql.ConnectionPool> {
+  if (!pool) {
+    pool = await sql.connect({
+      // ... config
+    })
+    
+    pool.on('error', (err) => {
+      console.error('SQL Server pool error', err)
+    })
+  }
+  return pool
+}
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  if (pool) {
+    await pool.close()
+  }
+  process.exit(0)
+})
+```
+
+### Parameterized Queries
+```typescript
+// Always use parameters to prevent SQL injection
+// ❌ WRONG
+await pool.request().query(`SELECT * FROM Users WHERE Email = '${email}'`)
+
+// ✅ CORRECT
+await pool.request()
+  .input('email', sql.NVarChar, email)
+  .query('SELECT * FROM Users WHERE Email = @email')
+```
+
+### Error Handling
+```typescript
+try {
+  const result = await pool.request()
+    .input('id', sql.Int, userId)
+    .query('SELECT * FROM Users WHERE Id = @id')
+  
+  if (result.recordset.length === 0) {
+    throw new Error('User not found')
+  }
+  return result.recordset[0]
+} catch (error: any) {
+  if (error.number === 2627) { // Unique constraint violation
+    throw new Error('Duplicate entry')
+  }
+  if (error.number === 547) { // Foreign key constraint violation
+    throw new Error('Referenced record does not exist')
+  }
+  throw error
+}
+```
+
+## Best Practices
+
+✅ **DO:**
+- Use connection pooling (10-20 connections)
+- Always use parameterized queries (@param)
+- Use transactions for multi-step operations
+- Create indexes on frequently queried columns
+- Use appropriate data types (NVarChar for Unicode)
+- Enable encryption in production
+- Use stored procedures for complex logic
+- Monitor connection pool usage
+- Use appropriate timeout values
+- Implement retry logic for transient errors
+
+❌ **DON'T:**
+- Use string concatenation for queries (SQL injection risk)
+- Create too many connections
+- Skip error handling
+- Ignore connection pool limits
+- Use SELECT * in production
+- Skip indexes on foreign keys
+- Hardcode connection strings
+- Skip encryption in production
+- Ignore query performance
+- Use synchronous operations
+
+## Configuration
+
+### Environment Variables
+```bash
+DB_HOST=localhost
+DB_PORT=1433
+DB_NAME=myapp
+DB_USER=sa
+DB_PASSWORD=securepassword
+```
+
+### Docker Compose
+```yaml
+services:
+  sqlserver:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    ports:
+      - "1433:1433"
+    environment:
+      ACCEPT_EULA: Y
+      SA_PASSWORD: securepassword
+      MSSQL_PID: Developer
+    volumes:
+      - sqlserver_data:/var/opt/mssql
+    healthcheck:
+      test: ["CMD-SHELL", "/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P securepassword -Q 'SELECT 1' || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  sqlserver_data:
+```
+
+## Integration with Development
+
+### Testing
+```typescript
+// Use test database
+const testPool = await sql.connect({
+  database: 'myapp_test',
+  // ... config
+})
+
+// Clean up after tests
+afterEach(async () => {
+  await testPool.request().query('DELETE FROM Users')
+  await testPool.request().query('DELETE FROM Posts')
+})
+```
+
+### Health Checks
+```typescript
+async function checkDatabaseHealth(): Promise<boolean> {
+  try {
+    const result = await pool.request().query('SELECT 1 AS Health')
+    return result.recordset.length > 0
+  } catch {
+    return false
+  }
+}
+```
+
+<!-- SQLSERVER:END -->
+

package/templates/workflows/codespell.yml

@@ -0,0 +1,31 @@
+name: Codespell
+
+on:
+  push:
+    branches: [ master, main, develop ]
+  pull_request:
+    branches: [ master, main, develop ]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Codespell
+        run: python -m pip install --upgrade 'codespell[toml]'
+
+      - name: Run Codespell
+        run: |
+          codespell \
+            --skip="*.lock,*.json,*.map,*.yaml,*.yml,*.csv,*.bib,target,node_modules,.git,dist,venv,build,benchmarks,coverage" \
+            --ignore-words-list="crate,ser,deser,upToDate,optIn,shouldBe,Bloc"
+          # MONOREPO NOTE: Add multilingual stopwords to ignore-words-list if needed
+          # Example: --ignore-words-list="crate,ser,deser,meu,oder,ist,alle" (Portuguese,German,etc)
+

package/templates/workflows/cpp-lint.yml

@@ -0,0 +1,47 @@
+name: C++ Lint
+
+on:
+  push:
+    branches: [ master, main, develop ]
+  pull_request:
+    branches: [ '**' ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v5
+    
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y clang-format-15 clang-tidy-15 cppcheck cmake ninja-build
+    
+    - name: Check formatting
+      run: |
+        find src include tests -name '*.cpp' -o -name '*.hpp' -o -name '*.h' | \
+        xargs clang-format-15 --dry-run --Werror
+    
+    - name: Configure CMake (for compile commands)
+      run: cmake -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+    
+    - name: Run clang-tidy
+      run: |
+        find src -name '*.cpp' | \
+        xargs clang-tidy-15 -p build --warnings-as-errors='*'
+    
+    - name: Run cppcheck
+      run: |
+        cppcheck --enable=all --error-exitcode=1 \
+          --suppress=missingIncludeSystem \
+          --suppress=unmatchedSuppression \
+          --inline-suppr \
+          -I include \
+          src/ tests/
+    
+    - name: Build with warnings as errors
+      run: |
+        cmake -B build -G Ninja -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic -Werror"
+        cmake --build build
+