@hivehub/rulebook 1.2.0

package/templates/services/NEO4J.md

@@ -0,0 +1,247 @@
+<!-- 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/ORACLE.md

@@ -0,0 +1,290 @@
+<!-- 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 -->
+