@hivehub/rulebook 5.5.1 → 5.7.0

package/templates/services/ORACLE.md

@@ -1,290 +0,0 @@
-<!-- ORACLE:START -->
-# Oracle Database Instructions
-
-**CRITICAL**: Use Oracle Database for enterprise relational data storage with advanced features, high availability, and comprehensive tooling.
-
-## Core Features
-
-### Connection
-```typescript
-// Using oracledb
-import oracledb from 'oracledb'
-
-oracledb.outFormat = oracledb.OUT_FORMAT_OBJECT
-oracledb.autoCommit = false
-
-const connection = await oracledb.getConnection({
-  user: process.env.DB_USER || 'system',
-  password: process.env.DB_PASSWORD,
-  connectString: `${process.env.DB_HOST || 'localhost'}:${process.env.DB_PORT || '1521'}/${process.env.DB_SERVICE || 'XE'}`,
-})
-
-// Connection pool
-const pool = await oracledb.createPool({
-  user: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  connectString: `${process.env.DB_HOST}:${process.env.DB_PORT}/${process.env.DB_SERVICE}`,
-  poolMin: 2,
-  poolMax: 10,
-  poolIncrement: 1,
-  poolTimeout: 60,
-})
-```
-
-### Basic Queries
-```typescript
-// SELECT
-const result = await connection.execute(
-  'SELECT * FROM Users WHERE Id = :id',
-  { id: userId }
-)
-const users = result.rows
-
-// INSERT with RETURNING
-const result = await connection.execute(
-  `INSERT INTO Users (Name, Email) 
-   VALUES (:name, :email) 
-   RETURNING Id INTO :id`,
-  {
-    name: 'John Doe',
-    email: 'john@example.com',
-    id: { type: oracledb.NUMBER, dir: oracledb.BIND_OUT },
-  }
-)
-const newId = result.outBinds.id[0]
-
-// UPDATE
-const result = await connection.execute(
-  'UPDATE Users SET Name = :name WHERE Id = :id',
-  {
-    name: 'Jane Doe',
-    id: userId,
-  }
-)
-
-// DELETE
-await connection.execute(
-  'DELETE FROM Users WHERE Id = :id',
-  { id: userId }
-)
-```
-
-### Transactions
-```typescript
-const connection = await pool.getConnection()
-
-try {
-  await connection.execute(
-    'INSERT INTO Accounts (UserId, Balance) VALUES (:userId, :balance)',
-    { userId, balance: 1000 }
-  )
-  
-  await connection.execute(
-    'INSERT INTO Transactions (AccountId, Amount) VALUES (:accountId, :amount)',
-    { accountId, amount: 1000 }
-  )
-  
-  await connection.commit()
-} catch (error) {
-  await connection.rollback()
-  throw error
-} finally {
-  await connection.close()
-}
-```
-
-### Advanced Features
-```typescript
-// PL/SQL procedures
-const result = await connection.execute(
-  `BEGIN
-     sp_GetUserDetails(:userId, :userData);
-   END;`,
-  {
-    userId,
-    userData: { type: oracledb.CURSOR, dir: oracledb.BIND_OUT },
-  }
-)
-
-// JSON operations (Oracle 12c+)
-const result = await connection.execute(
-  `SELECT 
-     Id,
-     Name,
-     JSON_VALUE(Metadata, '$.category') AS Category
-   FROM Products
-   WHERE JSON_VALUE(Metadata, '$.category') = :category`,
-  { category: 'electronics' }
-)
-
-// Full-text search (Oracle Text)
-const result = await connection.execute(
-  `SELECT * FROM Articles
-   WHERE CONTAINS(Content, :searchTerm, 1) > 0`,
-  { searchTerm: 'search term' }
-)
-
-// Window functions
-const result = await connection.execute(
-  `SELECT 
-     Name,
-     Salary,
-     ROW_NUMBER() OVER (PARTITION BY DepartmentId ORDER BY Salary DESC) AS Rank
-   FROM Employees`
-)
-```
-
-## Common Patterns
-
-### Connection Pooling
-```typescript
-let pool: oracledb.Pool | null = null
-
-export async function getPool(): Promise<oracledb.Pool> {
-  if (!pool) {
-    pool = await oracledb.createPool({
-      // ... config
-    })
-  }
-  return pool
-}
-
-// Graceful shutdown
-process.on('SIGINT', async () => {
-  if (pool) {
-    await pool.close()
-  }
-  process.exit(0)
-})
-```
-
-### Parameterized Queries
-```typescript
-// Always use bind variables (:param) to prevent SQL injection
-// ❌ WRONG
-await connection.execute(`SELECT * FROM Users WHERE Email = '${email}'`)
-
-// ✅ CORRECT
-await connection.execute(
-  'SELECT * FROM Users WHERE Email = :email',
-  { email }
-)
-```
-
-### Error Handling
-```typescript
-try {
-  const result = await connection.execute(
-    'SELECT * FROM Users WHERE Id = :id',
-    { id: userId }
-  )
-  
-  if (result.rows.length === 0) {
-    throw new Error('User not found')
-  }
-  return result.rows[0]
-} catch (error: any) {
-  if (error.errorNum === 1) { // Unique constraint violation
-    throw new Error('Duplicate entry')
-  }
-  if (error.errorNum === 2291) { // Foreign key constraint violation
-    throw new Error('Referenced record does not exist')
-  }
-  throw error
-}
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use connection pooling (2-10 connections typically)
-- Always use bind variables (:param)
-- Use transactions for multi-step operations
-- Create indexes on frequently queried columns
-- Use appropriate data types
-- Enable connection retry logic
-- Use PL/SQL for complex operations
-- Monitor connection pool usage
-- Use appropriate fetch array sizes
-- Implement proper error handling
-
-❌ **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 transaction management
-- Ignore query performance
-- Use synchronous operations
-
-## Configuration
-
-### Environment Variables
-```bash
-DB_HOST=localhost
-DB_PORT=1521
-DB_SERVICE=XE
-DB_USER=system
-DB_PASSWORD=securepassword
-```
-
-### Docker Compose
-```yaml
-services:
-  oracle:
-    image: container-registry.oracle.com/database/express:21.3.0-xe
-    ports:
-      - "1521:1521"
-      - "5500:5500"  # Enterprise Manager
-    environment:
-      ORACLE_PWD: securepassword
-    volumes:
-      - oracle_data:/opt/oracle/oradata
-    healthcheck:
-      test: ["CMD-SHELL", "sqlplus -S system/securepassword@localhost:1521/XE <<< 'SELECT 1 FROM DUAL;' || exit 1"]
-      interval: 30s
-      timeout: 10s
-      retries: 5
-
-volumes:
-  oracle_data:
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test database
-const testPool = await oracledb.createPool({
-  connectString: 'localhost:1521/TEST',
-  // ... config
-})
-
-// Clean up after tests
-afterEach(async () => {
-  const connection = await testPool.getConnection()
-  await connection.execute('DELETE FROM Users')
-  await connection.execute('DELETE FROM Posts')
-  await connection.close()
-})
-```
-
-### Health Checks
-```typescript
-async function checkDatabaseHealth(): Promise<boolean> {
-  try {
-    const connection = await pool.getConnection()
-    const result = await connection.execute('SELECT 1 FROM DUAL')
-    await connection.close()
-    return result.rows.length > 0
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- ORACLE:END -->
-

package/templates/services/PINO.md

@@ -1,24 +0,0 @@
-<!-- PINO:START -->
-# Pino — Structured Logging
-
-## Configuration
-- Create singleton logger instance: `const logger = pino({ level: process.env.LOG_LEVEL || 'info' })`
-- Use child loggers for request context: `req.log = logger.child({ requestId: req.id })`
-- Configure pretty print for development only: `transport: { target: 'pino-pretty' }` (only when `NODE_ENV !== 'production'`)
-
-## Log Levels
-- `error`: Unexpected errors requiring immediate attention
-- `warn`: Recoverable errors, deprecated usage, approaching limits
-- `info`: Significant state changes, important business events
-- `debug`: Detailed flow for troubleshooting (disabled in production)
-- `trace`: High-frequency diagnostic data (never in production)
-
-## Structured Fields
-- Always include: `{ service, version, requestId, userId }` in request context
-- Never log: passwords, tokens, credit cards, PII fields
-- Log all outgoing HTTP calls with: `{ method, url, statusCode, duration }`
-
-## Performance
-- Avoid `JSON.stringify()` in log calls — pino handles serialization
-- Use `logger.isLevelEnabled('debug')` before expensive debug computations
-<!-- PINO:END -->

package/templates/services/POSTGRESQL.md

@@ -1,326 +0,0 @@
-<!-- POSTGRESQL:START -->
-# PostgreSQL Database Instructions
-
-**CRITICAL**: Use PostgreSQL for relational data storage with ACID compliance, transactions, and advanced features.
-
-## Core Features
-
-### Connection
-```typescript
-// Using pg (Node.js)
-import { Pool } from 'pg'
-const pool = new Pool({
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT || '5432'),
-  database: process.env.DB_NAME,
-  user: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
-  max: 20,
-  idleTimeoutMillis: 30000,
-  connectionTimeoutMillis: 2000,
-})
-
-// Using Prisma
-import { PrismaClient } from '@prisma/client'
-const prisma = new PrismaClient()
-```
-
-### Basic Queries
-```typescript
-// SELECT
-const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId])
-const users = result.rows
-
-// INSERT
-const result = await pool.query(
-  'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
-  ['John Doe', 'john@example.com']
-)
-const newUser = result.rows[0]
-
-// UPDATE
-const result = await pool.query(
-  'UPDATE users SET name = $1 WHERE id = $2 RETURNING *',
-  ['Jane Doe', userId]
-)
-
-// DELETE
-await pool.query('DELETE FROM users WHERE id = $1', [userId])
-```
-
-### Transactions
-```typescript
-const client = await pool.connect()
-try {
-  await client.query('BEGIN')
-  
-  await client.query('INSERT INTO accounts (user_id, balance) VALUES ($1, $2)', [userId, 1000])
-  await client.query('INSERT INTO transactions (account_id, amount) VALUES ($1, $2)', [accountId, 1000])
-  
-  await client.query('COMMIT')
-} catch (error) {
-  await client.query('ROLLBACK')
-  throw error
-} finally {
-  client.release()
-}
-```
-
-### Advanced Features
-```typescript
-// JSONB queries
-await pool.query(
-  'SELECT * FROM products WHERE metadata @> $1',
-  [JSON.stringify({ category: 'electronics' })]
-)
-
-// Full-text search
-await pool.query(
-  "SELECT * FROM articles WHERE to_tsvector('english', content) @@ to_tsquery('english', $1)",
-  ['search term']
-)
-
-// Array operations
-await pool.query('SELECT * FROM posts WHERE tags && $1', [['javascript', 'typescript']])
-
-// Window functions
-await pool.query(`
-  SELECT 
-    name,
-    salary,
-    ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) as rank
-  FROM employees
-`)
-```
-
-## Common Patterns
-
-### Connection Pooling
-```typescript
-// Reuse connection pool
-let pool: Pool | null = null
-
-export function getPool(): Pool {
-  if (!pool) {
-    pool = new Pool({
-      // ... config
-    })
-    
-    pool.on('error', (err) => {
-      console.error('Unexpected error on idle client', err)
-      process.exit(-1)
-    })
-  }
-  return pool
-}
-
-// Graceful shutdown
-process.on('SIGINT', async () => {
-  if (pool) {
-    await pool.end()
-  }
-  process.exit(0)
-})
-```
-
-### Prepared Statements
-```typescript
-// Always use parameterized queries to prevent SQL injection
-// ❌ WRONG
-await pool.query(`SELECT * FROM users WHERE email = '${email}'`)
-
-// ✅ CORRECT
-await pool.query('SELECT * FROM users WHERE email = $1', [email])
-```
-
-### Error Handling
-```typescript
-try {
-  const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId])
-  if (result.rows.length === 0) {
-    throw new Error('User not found')
-  }
-  return result.rows[0]
-} catch (error) {
-  if (error.code === '23505') { // Unique violation
-    throw new Error('Duplicate entry')
-  }
-  if (error.code === '23503') { // Foreign key violation
-    throw new Error('Referenced record does not exist')
-  }
-  throw error
-}
-```
-
-### Migrations
-```typescript
-// Using node-pg-migrate
-import { migrate } from 'node-pg-migrate'
-
-await migrate({
-  databaseUrl: process.env.DATABASE_URL,
-  dir: 'migrations',
-  direction: 'up',
-  migrationsTable: 'pgmigrations',
-  dryRun: false,
-})
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use connection pooling (max 20-30 connections)
-- Always use parameterized queries ($1, $2, etc.)
-- Use transactions for multi-step operations
-- Create indexes on frequently queried columns
-- Use EXPLAIN ANALYZE to optimize queries
-- Enable connection pooling (PgBouncer for production)
-- Use SSL in production
-- Set appropriate connection timeouts
-- Monitor connection pool usage
-- Use prepared statements for repeated queries
-
-❌ **DON'T:**
-- Use string concatenation for queries (SQL injection risk)
-- Create too many connections (exhaust pool)
-- Skip error handling
-- Ignore connection pool limits
-- Use SELECT * in production (specify columns)
-- Skip indexes on foreign keys
-- Hardcode connection strings
-- Skip SSL in production
-- Ignore query performance
-- Use synchronous queries
-
-## Configuration
-
-### Environment Variables
-```bash
-DB_HOST=localhost
-DB_PORT=5432
-DB_NAME=myapp
-DB_USER=myuser
-DB_PASSWORD=securepassword
-DATABASE_URL=postgresql://user:password@host:port/database
-```
-
-### Docker Compose
-```yaml
-services:
-  postgres:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_DB: myapp
-      POSTGRES_USER: myuser
-      POSTGRES_PASSWORD: securepassword
-    ports:
-      - "5432:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U myuser"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  postgres_data:
-```
-
-### Prisma Schema
-```prisma
-datasource db {
-  provider = "postgresql"
-  url      = env("DATABASE_URL")
-}
-
-model User {
-  id        Int      @id @default(autoincrement())
-  email     String   @unique
-  name      String?
-  createdAt DateTime @default(now())
-  posts     Post[]
-}
-
-model Post {
-  id        Int      @id @default(autoincrement())
-  title     String
-  content   String?
-  authorId  Int
-  author    User     @relation(fields: [authorId], references: [id])
-  createdAt DateTime @default(now())
-}
-```
-
-## Performance Optimization
-
-### Indexing
-```sql
--- Single column index
-CREATE INDEX idx_users_email ON users(email);
-
--- Composite index
-CREATE INDEX idx_posts_author_created ON posts(author_id, created_at DESC);
-
--- Partial index
-CREATE INDEX idx_active_users ON users(email) WHERE active = true;
-
--- GIN index for JSONB
-CREATE INDEX idx_products_metadata ON products USING GIN(metadata);
-```
-
-### Query Optimization
-```typescript
-// Use LIMIT and OFFSET for pagination
-const result = await pool.query(
-  'SELECT * FROM posts ORDER BY created_at DESC LIMIT $1 OFFSET $2',
-  [limit, offset]
-)
-
-// Use EXISTS instead of COUNT for existence checks
-const result = await pool.query(
-  'SELECT EXISTS(SELECT 1 FROM users WHERE email = $1)',
-  [email]
-)
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test database
-const testPool = new Pool({
-  database: 'myapp_test',
-  // ... config
-})
-
-// Clean up after tests
-afterEach(async () => {
-  await testPool.query('TRUNCATE TABLE users, posts CASCADE')
-})
-
-// Use transactions for test isolation
-beforeEach(async () => {
-  await testPool.query('BEGIN')
-})
-
-afterEach(async () => {
-  await testPool.query('ROLLBACK')
-})
-```
-
-### Health Checks
-```typescript
-async function checkDatabaseHealth(): Promise<boolean> {
-  try {
-    const result = await pool.query('SELECT 1')
-    return result.rows.length > 0
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- POSTGRESQL:END -->
-

package/templates/services/PROMETHEUS.md

@@ -1,33 +0,0 @@
-<!-- PROMETHEUS:START -->
-# Prometheus — Metrics
-
-## Setup
-```typescript
-import { Registry, collectDefaultMetrics } from 'prom-client';
-const registry = new Registry();
-collectDefaultMetrics({ register: registry });
-```
-
-Expose metrics endpoint:
-```typescript
-app.get('/metrics', async (req, res) => {
-  res.set('Content-Type', registry.contentType);
-  res.end(await registry.metrics());
-});
-```
-
-## Metric Types
-- **Counter**: Monotonically increasing values (`http_requests_total`)
-- **Gauge**: Values that go up and down (`active_connections`, memory usage)
-- **Histogram**: Duration/size distributions (`http_request_duration_seconds`)
-- **Summary**: Percentile calculations (use Histogram instead when possible)
-
-## Naming Conventions
-- Format: `<namespace>_<metric_name>_<unit>` (e.g., `app_http_request_duration_seconds`)
-- Use `_total` suffix for counters
-- Include all relevant labels: `{ method, route, status_code }`
-
-## Alerting
-- Define recording rules for frequently queried expressions
-- Set alert thresholds: error rate > 5%, p99 latency > 2s, memory > 80%
-<!-- PROMETHEUS:END -->