@hivehub/rulebook 5.5.2 → 5.7.0

package/templates/services/MYSQL.md

@@ -1,358 +0,0 @@
-<!-- MYSQL:START -->
-# MySQL Database Instructions
-
-**CRITICAL**: Use MySQL for relational data storage with high performance, replication, and wide ecosystem support.
-
-## Core Features
-
-### Connection
-```typescript
-// Using mysql2 (Node.js)
-import mysql from 'mysql2/promise'
-
-const pool = mysql.createPool({
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT || '3306'),
-  database: process.env.DB_NAME,
-  user: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  waitForConnections: true,
-  connectionLimit: 10,
-  queueLimit: 0,
-  enableKeepAlive: true,
-  keepAliveInitialDelay: 0,
-})
-
-// Using Prisma
-import { PrismaClient } from '@prisma/client'
-const prisma = new PrismaClient()
-```
-
-### Basic Queries
-```typescript
-// SELECT
-const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId])
-const users = rows as User[]
-
-// INSERT
-const [result] = await pool.execute(
-  'INSERT INTO users (name, email) VALUES (?, ?)',
-  ['John Doe', 'john@example.com']
-)
-const insertId = (result as any).insertId
-
-// UPDATE
-const [result] = await pool.execute(
-  'UPDATE users SET name = ? WHERE id = ?',
-  ['Jane Doe', userId]
-)
-const affectedRows = (result as any).affectedRows
-
-// DELETE
-const [result] = await pool.execute('DELETE FROM users WHERE id = ?', [userId])
-```
-
-### Transactions
-```typescript
-const connection = await pool.getConnection()
-try {
-  await connection.beginTransaction()
-  
-  await connection.execute('INSERT INTO accounts (user_id, balance) VALUES (?, ?)', [userId, 1000])
-  await connection.execute('INSERT INTO transactions (account_id, amount) VALUES (?, ?)', [accountId, 1000])
-  
-  await connection.commit()
-} catch (error) {
-  await connection.rollback()
-  throw error
-} finally {
-  connection.release()
-}
-```
-
-### Advanced Features
-```typescript
-// JSON queries (MySQL 5.7+)
-const [rows] = await pool.execute(
-  "SELECT * FROM products WHERE JSON_EXTRACT(metadata, '$.category') = ?",
-  ['electronics']
-)
-
-// Full-text search
-const [rows] = await pool.execute(
-  "SELECT * FROM articles WHERE MATCH(title, content) AGAINST(? IN NATURAL LANGUAGE MODE)",
-  ['search term']
-)
-
-// Window functions (MySQL 8.0+)
-const [rows] = await pool.execute(`
-  SELECT 
-    name,
-    salary,
-    ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) as rank
-  FROM employees
-`)
-
-// Common Table Expressions (CTE) (MySQL 8.0+)
-const [rows] = await pool.execute(`
-  WITH RECURSIVE cte AS (
-    SELECT id, name, parent_id FROM categories WHERE parent_id IS NULL
-    UNION ALL
-    SELECT c.id, c.name, c.parent_id FROM categories c
-    INNER JOIN cte ON c.parent_id = cte.id
-  )
-  SELECT * FROM cte
-`)
-```
-
-## Common Patterns
-
-### Connection Pooling
-```typescript
-// Reuse connection pool
-let pool: mysql.Pool | null = null
-
-export function getPool(): mysql.Pool {
-  if (!pool) {
-    pool = mysql.createPool({
-      // ... config
-    })
-    
-    pool.on('connection', (connection) => {
-      connection.query('SET SESSION sql_mode = "STRICT_TRANS_TABLES"')
-    })
-  }
-  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.execute(`SELECT * FROM users WHERE email = '${email}'`)
-
-// ✅ CORRECT
-await pool.execute('SELECT * FROM users WHERE email = ?', [email])
-```
-
-### Error Handling
-```typescript
-try {
-  const [rows] = await pool.execute('SELECT * FROM users WHERE id = ?', [userId])
-  if ((rows as any[]).length === 0) {
-    throw new Error('User not found')
-  }
-  return rows[0]
-} catch (error: any) {
-  if (error.code === 'ER_DUP_ENTRY') {
-    throw new Error('Duplicate entry')
-  }
-  if (error.code === 'ER_NO_REFERENCED_ROW_2') {
-    throw new Error('Referenced record does not exist')
-  }
-  throw error
-}
-```
-
-### Migrations
-```typescript
-// Using db-migrate
-import { migrate } from 'db-migrate'
-
-await migrate({
-  config: {
-    dev: {
-      driver: 'mysql',
-      database: process.env.DB_NAME,
-      user: process.env.DB_USER,
-      password: process.env.DB_PASSWORD,
-      host: process.env.DB_HOST,
-    }
-  },
-  env: 'dev',
-})
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use connection pooling (10-20 connections typically)
-- Always use parameterized queries (? placeholders)
-- Use transactions for multi-step operations
-- Create indexes on frequently queried columns
-- Use EXPLAIN to optimize queries
-- Enable query caching for read-heavy workloads
-- Use InnoDB engine (ACID compliance)
-- Set appropriate charset (utf8mb4 for full Unicode)
-- Monitor slow query log
-- 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
-- Use MyISAM engine (no transactions)
-- Ignore query performance
-- Use synchronous queries
-
-## Configuration
-
-### Environment Variables
-```bash
-DB_HOST=localhost
-DB_PORT=3306
-DB_NAME=myapp
-DB_USER=myuser
-DB_PASSWORD=securepassword
-DATABASE_URL=mysql://user:password@host:port/database
-```
-
-### Docker Compose
-```yaml
-services:
-  mysql:
-    image: mysql:8.0
-    environment:
-      MYSQL_DATABASE: myapp
-      MYSQL_USER: myuser
-      MYSQL_PASSWORD: securepassword
-      MYSQL_ROOT_PASSWORD: rootpassword
-    ports:
-      - "3306:3306"
-    volumes:
-      - mysql_data:/var/lib/mysql
-    command: --default-authentication-plugin=mysql_native_password
-    healthcheck:
-      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  mysql_data:
-```
-
-### Prisma Schema
-```prisma
-datasource db {
-  provider = "mysql"
-  url      = env("DATABASE_URL")
-}
-
-model User {
-  id        Int      @id @default(autoincrement())
-  email     String   @unique @db.VarChar(255)
-  name      String?  @db.VarChar(255)
-  createdAt DateTime @default(now()) @db.Timestamp(6)
-  posts     Post[]
-}
-
-model Post {
-  id        Int      @id @default(autoincrement())
-  title     String   @db.VarChar(255)
-  content   String?  @db.Text
-  authorId  Int
-  author    User     @relation(fields: [authorId], references: [id])
-  createdAt DateTime @default(now()) @db.Timestamp(6)
-  
-  @@index([authorId, createdAt(sort: Desc)])
-}
-```
-
-## 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);
-
--- Full-text index
-CREATE FULLTEXT INDEX idx_articles_content ON articles(title, content);
-
--- Prefix index (for long strings)
-CREATE INDEX idx_users_name_prefix ON users(name(10));
-```
-
-### Query Optimization
-```typescript
-// Use LIMIT for pagination
-const [rows] = await pool.execute(
-  'SELECT * FROM posts ORDER BY created_at DESC LIMIT ? OFFSET ?',
-  [limit, offset]
-)
-
-// Use EXISTS instead of COUNT
-const [rows] = await pool.execute(
-  'SELECT EXISTS(SELECT 1 FROM users WHERE email = ?) as exists',
-  [email]
-)
-
-// Use JOIN instead of subqueries when possible
-const [rows] = await pool.execute(`
-  SELECT u.*, COUNT(p.id) as post_count
-  FROM users u
-  LEFT JOIN posts p ON u.id = p.author_id
-  GROUP BY u.id
-`)
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test database
-const testPool = mysql.createPool({
-  database: 'myapp_test',
-  // ... config
-})
-
-// Clean up after tests
-afterEach(async () => {
-  await testPool.execute('SET FOREIGN_KEY_CHECKS = 0')
-  await testPool.execute('TRUNCATE TABLE users')
-  await testPool.execute('TRUNCATE TABLE posts')
-  await testPool.execute('SET FOREIGN_KEY_CHECKS = 1')
-})
-
-// Use transactions for test isolation
-beforeEach(async () => {
-  const connection = await testPool.getConnection()
-  await connection.beginTransaction()
-  // Store connection for rollback
-})
-
-afterEach(async () => {
-  // Rollback transaction
-})
-```
-
-### Health Checks
-```typescript
-async function checkDatabaseHealth(): Promise<boolean> {
-  try {
-    const [rows] = await pool.execute('SELECT 1 as health')
-    return (rows as any[]).length > 0
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- MYSQL:END -->
-

package/templates/services/NEO4J.md

@@ -1,247 +0,0 @@
-<!-- NEO4J:START -->
-# Neo4j Graph Database Instructions
-
-**CRITICAL**: Use Neo4j for graph data modeling, relationship traversal, and complex connected data queries.
-
-## Core Features
-
-### Connection
-```typescript
-// Using neo4j-driver
-import neo4j from 'neo4j-driver'
-
-const driver = neo4j.driver(
-  process.env.NEO4J_URI || 'bolt://localhost:7687',
-  neo4j.auth.basic(
-    process.env.NEO4J_USER || 'neo4j',
-    process.env.NEO4J_PASSWORD || 'password'
-  ),
-  {
-    maxConnectionLifetime: 3 * 60 * 60 * 1000, // 3 hours
-    maxConnectionPoolSize: 50,
-    connectionAcquisitionTimeout: 2 * 60 * 1000, // 2 minutes
-  }
-)
-
-const session = driver.session()
-```
-
-### Basic Operations
-```typescript
-// Create node
-const result = await session.run(
-  'CREATE (u:User {id: $id, name: $name, email: $email}) RETURN u',
-  { id: '1', name: 'John Doe', email: 'john@example.com' }
-)
-
-// Create relationship
-await session.run(
-  'MATCH (u:User {id: $userId}), (p:Post {id: $postId}) CREATE (u)-[:CREATED]->(p)',
-  { userId: '1', postId: '1' }
-)
-
-// Find nodes
-const result = await session.run(
-  'MATCH (u:User {email: $email}) RETURN u',
-  { email: 'john@example.com' }
-)
-const user = result.records[0]?.get('u')
-
-// Update node
-await session.run(
-  'MATCH (u:User {id: $id}) SET u.name = $name, u.updatedAt = $updatedAt',
-  { id: '1', name: 'Jane Doe', updatedAt: new Date().toISOString() }
-)
-
-// Delete node and relationships
-await session.run(
-  'MATCH (u:User {id: $id}) DETACH DELETE u',
-  { id: '1' }
-)
-```
-
-### Advanced Queries
-```typescript
-// Find relationships
-const result = await session.run(`
-  MATCH (u:User)-[r:FOLLOWS]->(f:User)
-  WHERE u.id = $userId
-  RETURN f, r.createdAt
-  ORDER BY r.createdAt DESC
-  LIMIT 10
-`, { userId: '1' })
-
-// Shortest path
-const result = await session.run(`
-  MATCH path = shortestPath(
-    (start:User {id: $startId})-[*]-(end:User {id: $endId})
-  )
-  RETURN path, length(path) as distance
-`, { startId: '1', endId: '2' })
-
-// Pattern matching
-const result = await session.run(`
-  MATCH (u:User)-[:CREATED]->(p:Post)-[:TAGGED_WITH]->(t:Tag)
-  WHERE t.name = $tagName
-  RETURN u, count(p) as postCount
-  ORDER BY postCount DESC
-`, { tagName: 'javascript' })
-
-// Aggregations
-const result = await session.run(`
-  MATCH (u:User)-[:FOLLOWS]->(f:User)
-  RETURN u.id, count(f) as followerCount
-  ORDER BY followerCount DESC
-  LIMIT 10
-`)
-```
-
-## Common Patterns
-
-### User Recommendations
-```typescript
-async function getRecommendedUsers(userId: string) {
-  const result = await session.run(`
-    MATCH (u:User {id: $userId})-[:FOLLOWS]->(f:User)-[:FOLLOWS]->(recommended:User)
-    WHERE NOT (u)-[:FOLLOWS]->(recommended) AND u <> recommended
-    RETURN recommended, count(recommended) as mutualFollowers
-    ORDER BY mutualFollowers DESC
-    LIMIT 10
-  `, { userId })
-  
-  return result.records.map(record => ({
-    user: record.get('recommended').properties,
-    score: record.get('mutualFollowers').toNumber(),
-  }))
-}
-```
-
-### Graph Traversal
-```typescript
-async function findConnections(userId: string, depth: number) {
-  const result = await session.run(`
-    MATCH path = (start:User {id: $userId})-[*1..${depth}]-(connected:User)
-    RETURN connected, length(path) as distance
-    ORDER BY distance
-  `, { userId })
-  
-  return result.records.map(record => ({
-    user: record.get('connected').properties,
-    distance: record.get('distance').toNumber(),
-  }))
-}
-```
-
-### Transaction
-```typescript
-const session = driver.session()
-const tx = session.beginTransaction()
-
-try {
-  await tx.run('CREATE (u:User {id: $id, name: $name})', { id: '1', name: 'John' })
-  await tx.run('CREATE (p:Post {id: $id, title: $title})', { id: '1', title: 'Post 1' })
-  await tx.run(
-    'MATCH (u:User {id: $userId}), (p:Post {id: $postId}) CREATE (u)-[:CREATED]->(p)',
-    { userId: '1', postId: '1' }
-  )
-  await tx.commit()
-} catch (error) {
-  await tx.rollback()
-  throw error
-} finally {
-  await session.close()
-}
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use parameterized queries ($param)
-- Create indexes on frequently queried properties
-- Use appropriate relationship types
-- Batch operations when possible
-- Close sessions after use
-- Use transactions for multi-step operations
-- Monitor query performance
-- Use appropriate data types
-- Implement connection pooling
-- Use labels effectively
-
-❌ **DON'T:**
-- Use string concatenation for queries (injection risk)
-- Create too many relationships per node
-- Skip error handling
-- Ignore query performance
-- Hardcode connection strings
-- Store large properties (use external storage)
-- Skip indexes on lookup properties
-- Ignore transaction boundaries
-- Use synchronous operations
-- Store sensitive data without encryption
-
-## Configuration
-
-### Environment Variables
-```bash
-NEO4J_URI=bolt://localhost:7687
-NEO4J_URI=neo4j+s://cluster.example.com:7687  # SSL
-NEO4J_USER=neo4j
-NEO4J_PASSWORD=securepassword
-```
-
-### Docker Compose
-```yaml
-services:
-  neo4j:
-    image: neo4j:5
-    ports:
-      - "7474:7474"  # HTTP
-      - "7687:7687"  # Bolt
-    environment:
-      NEO4J_AUTH: neo4j/securepassword
-      NEO4J_PLUGINS: '["apoc"]'
-    volumes:
-      - neo4j_data:/data
-      - neo4j_logs:/logs
-    healthcheck:
-      test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "securepassword", "RETURN 1"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-volumes:
-  neo4j_data:
-  neo4j_logs:
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test database
-const testDriver = neo4j.driver('bolt://localhost:7688', neo4j.auth.basic('neo4j', 'test'))
-
-// Clean up after tests
-afterEach(async () => {
-  const session = testDriver.session()
-  await session.run('MATCH (n) DETACH DELETE n')
-  await session.close()
-})
-```
-
-### Health Checks
-```typescript
-async function checkNeo4jHealth(): Promise<boolean> {
-  try {
-    const session = driver.session()
-    const result = await session.run('RETURN 1 as health')
-    await session.close()
-    return result.records.length > 0
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- NEO4J:END -->
-

package/templates/services/OPENTELEMETRY.md

@@ -1,25 +0,0 @@
-<!-- OPENTELEMETRY:START -->
-# OpenTelemetry — Distributed Tracing
-
-## Initialization
-- Initialize OTel SDK BEFORE application code (use `--require` flag or top-level import)
-- Configure exporter based on environment (OTLP, Jaeger, console for dev)
-- Set `serviceName` from environment: `process.env.OTEL_SERVICE_NAME`
-
-## Instrumentation
-- Use auto-instrumentation packages for common libraries (HTTP, Express, pg)
-- Create manual spans for business logic operations:
-  ```typescript
-  const tracer = trace.getTracer('service-name');
-  const span = tracer.startSpan('operation.name');
-  try { ... } finally { span.end(); }
-  ```
-
-## Context Propagation
-- Always propagate context across service boundaries using W3C Trace Context headers
-- Use `context.with()` for async operations to preserve trace context
-
-## Metrics
-- Use `@opentelemetry/sdk-metrics` for custom metrics
-- Follow naming conventions: `<namespace>.<metric_type>.<name>` (e.g., `http.server.request_count`)
-<!-- OPENTELEMETRY:END -->