@hivehub/rulebook 5.5.1 → 5.7.0

package/templates/services/S3.md

@@ -1,298 +0,0 @@
-<!-- S3:START -->
-# AWS S3 Storage Instructions
-
-**CRITICAL**: Use AWS S3 for object storage, file uploads, static assets, and backup storage with high availability.
-
-## Core Features
-
-### Connection
-```typescript
-// Using @aws-sdk/client-s3
-import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3'
-
-const s3Client = new S3Client({
-  region: process.env.AWS_REGION || 'us-east-1',
-  credentials: {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID || '',
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY || '',
-  },
-})
-
-// Using AWS SDK v2
-import AWS from 'aws-sdk'
-
-const s3 = new AWS.S3({
-  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-  region: process.env.AWS_REGION || 'us-east-1',
-})
-```
-
-### Basic Operations
-```typescript
-// Upload file
-const uploadParams = {
-  Bucket: process.env.S3_BUCKET || 'my-bucket',
-  Key: 'path/to/file.jpg',
-  Body: fileBuffer,
-  ContentType: 'image/jpeg',
-  ACL: 'private', // or 'public-read'
-}
-
-await s3Client.send(new PutObjectCommand(uploadParams))
-
-// Upload with metadata
-await s3Client.send(new PutObjectCommand({
-  ...uploadParams,
-  Metadata: {
-    userId: '123',
-    originalName: 'photo.jpg',
-  },
-  TagSet: [
-    { Key: 'category', Value: 'profile' },
-  ],
-}))
-
-// Get file
-const getParams = {
-  Bucket: process.env.S3_BUCKET,
-  Key: 'path/to/file.jpg',
-}
-
-const response = await s3Client.send(new GetObjectCommand(getParams))
-const fileContent = await response.Body?.transformToByteArray()
-
-// Delete file
-await s3Client.send(new DeleteObjectCommand({
-  Bucket: process.env.S3_BUCKET,
-  Key: 'path/to/file.jpg',
-}))
-```
-
-### Advanced Features
-```typescript
-// Presigned URL for upload
-import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
-
-const command = new PutObjectCommand({
-  Bucket: process.env.S3_BUCKET,
-  Key: 'uploads/file.jpg',
-  ContentType: 'image/jpeg',
-})
-
-const presignedUrl = await getSignedUrl(s3Client, command, { expiresIn: 3600 })
-
-// Presigned URL for download
-const getCommand = new GetObjectCommand({
-  Bucket: process.env.S3_BUCKET,
-  Key: 'path/to/file.jpg',
-})
-
-const downloadUrl = await getSignedUrl(s3Client, getCommand, { expiresIn: 3600 })
-
-// Multipart upload (for large files)
-import { CreateMultipartUploadCommand, UploadPartCommand, CompleteMultipartUploadCommand } from '@aws-sdk/client-s3'
-
-const createCommand = new CreateMultipartUploadCommand({
-  Bucket: process.env.S3_BUCKET,
-  Key: 'large-file.zip',
-  ContentType: 'application/zip',
-})
-
-const { UploadId } = await s3Client.send(createCommand)
-
-// Upload parts
-const part1 = await s3Client.send(new UploadPartCommand({
-  Bucket: process.env.S3_BUCKET,
-  Key: 'large-file.zip',
-  PartNumber: 1,
-  UploadId,
-  Body: part1Buffer,
-}))
-
-// Complete upload
-await s3Client.send(new CompleteMultipartUploadCommand({
-  Bucket: process.env.S3_BUCKET,
-  Key: 'large-file.zip',
-  UploadId,
-  MultipartUpload: {
-    Parts: [
-      { PartNumber: 1, ETag: part1.ETag },
-    ],
-  },
-}))
-
-// List objects
-import { ListObjectsV2Command } from '@aws-sdk/client-s3'
-
-const listCommand = new ListObjectsV2Command({
-  Bucket: process.env.S3_BUCKET,
-  Prefix: 'uploads/',
-  MaxKeys: 100,
-})
-
-const { Contents } = await s3Client.send(listCommand)
-```
-
-## Common Patterns
-
-### File Upload Handler
-```typescript
-async function uploadFile(file: Buffer, filename: string, userId: string) {
-  const key = `users/${userId}/${Date.now()}-${filename}`
-  
-  await s3Client.send(new PutObjectCommand({
-    Bucket: process.env.S3_BUCKET,
-    Key: key,
-    Body: file,
-    ContentType: getContentType(filename),
-    Metadata: {
-      userId,
-      originalName: filename,
-      uploadedAt: new Date().toISOString(),
-    },
-  }))
-  
-  return {
-    key,
-    url: `https://${process.env.S3_BUCKET}.s3.${process.env.AWS_REGION}.amazonaws.com/${key}`,
-  }
-}
-```
-
-### Temporary File Access
-```typescript
-async function generateTemporaryDownloadUrl(key: string, expiresIn: number = 3600) {
-  const command = new GetObjectCommand({
-    Bucket: process.env.S3_BUCKET,
-    Key: key,
-  })
-  
-  return await getSignedUrl(s3Client, command, { expiresIn })
-}
-```
-
-### File Cleanup
-```typescript
-async function deleteFilesByPrefix(prefix: string) {
-  const listCommand = new ListObjectsV2Command({
-    Bucket: process.env.S3_BUCKET,
-    Prefix: prefix,
-  })
-  
-  let continuationToken: string | undefined
-  
-  do {
-    const response = await s3Client.send({
-      ...listCommand,
-      ContinuationToken: continuationToken,
-    })
-    
-    if (response.Contents) {
-      for (const object of response.Contents) {
-        if (object.Key) {
-          await s3Client.send(new DeleteObjectCommand({
-            Bucket: process.env.S3_BUCKET,
-            Key: object.Key,
-          }))
-        }
-      }
-    }
-    
-    continuationToken = response.NextContinuationToken
-  } while (continuationToken)
-}
-```
-
-## Best Practices
-
-✅ **DO:**
-- Use presigned URLs for client uploads
-- Set appropriate Content-Type headers
-- Use versioning for important files
-- Implement lifecycle policies for cleanup
-- Use multipart upload for files > 5MB
-- Enable encryption (SSE-S3 or SSE-KMS)
-- Use appropriate storage classes (Standard, IA, Glacier)
-- Implement proper error handling
-- Use bucket policies for access control
-- Monitor bucket usage and costs
-
-❌ **DON'T:**
-- Store sensitive data without encryption
-- Use public-read ACL unnecessarily
-- Hardcode credentials
-- Ignore error handling
-- Skip content-type validation
-- Store large files without multipart upload
-- Ignore lifecycle policies
-- Skip access logging
-- Use default bucket policies
-- Ignore cost optimization
-
-## Configuration
-
-### Environment Variables
-```bash
-AWS_REGION=us-east-1
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
-S3_BUCKET=my-bucket
-```
-
-### IAM Policy
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "s3:PutObject",
-        "s3:GetObject",
-        "s3:DeleteObject"
-      ],
-      "Resource": "arn:aws:s3:::my-bucket/*"
-    }
-  ]
-}
-```
-
-## Integration with Development
-
-### Testing
-```typescript
-// Use test bucket or LocalStack
-const testS3Client = new S3Client({
-  endpoint: 'http://localhost:4566', // LocalStack
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: 'test',
-    secretAccessKey: 'test',
-  },
-  forcePathStyle: true,
-})
-
-// Clean up after tests
-afterEach(async () => {
-  // Delete test files
-})
-```
-
-### Health Checks
-```typescript
-async function checkS3Health(): Promise<boolean> {
-  try {
-    await s3Client.send(new ListObjectsV2Command({
-      Bucket: process.env.S3_BUCKET,
-      MaxKeys: 1,
-    }))
-    return true
-  } catch {
-    return false
-  }
-}
-```
-
-<!-- S3:END -->
-

package/templates/services/SENTRY.md

@@ -1,23 +0,0 @@
-<!-- SENTRY:START -->
-# Sentry — Error Tracking
-
-## Configuration
-- Initialize Sentry at application entry point BEFORE other imports
-- Set `dsn` from environment variable: `process.env.SENTRY_DSN`
-- Configure `environment` from `NODE_ENV`
-- Enable `tracesSampleRate: 0.1` in production (not 1.0)
-
-## Error Capture
-- Wrap route handlers with Sentry error middleware
-- Use `Sentry.captureException(err)` in catch blocks for unexpected errors
-- Add custom context: `Sentry.setContext('user', { id, email })`
-- Never log sensitive data (passwords, tokens) in Sentry context
-
-## Release Tracking
-- Set `release` using git commit SHA: `process.env.SENTRY_RELEASE`
-- Run `sentry-cli releases` in CI to associate commits with releases
-
-## Performance
-- Use `Sentry.startTransaction()` for tracking custom operations
-- Add distributed tracing headers to internal service calls
-<!-- SENTRY:END -->

package/templates/services/SQLITE.md

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