red64-cli 0.1.0 → 0.3.0

package/framework/stacks/nextjs/migrations.md

@@ -0,0 +1,332 @@
+# Prisma Migrations
+
+Database migration workflow for Prisma ORM with zero-downtime strategies, seed data, and production deployment.
+
+---
+
+## Philosophy
+
+- **Schema-first**: Change `schema.prisma`, then generate the migration
+- **Version-controlled**: Every migration is committed and never modified after deployment
+- **Reversible in practice**: Plan rollback strategies even though Prisma does not generate down migrations
+- **Zero-downtime by default**: Structure changes to avoid locking tables or breaking running code
+
+---
+
+## Migration Workflow
+
+### Development Cycle
+
+```bash
+# 1. Edit schema.prisma
+# 2. Generate and apply migration
+pnpm prisma migrate dev --name add_user_bio
+
+# 3. Prisma automatically:
+#    - Generates SQL migration file
+#    - Applies it to development database
+#    - Regenerates Prisma Client
+```
+
+### Migration Commands
+
+| Command | Purpose | Environment |
+|---|---|---|
+| `prisma migrate dev` | Create and apply migration | Development |
+| `prisma migrate dev --name <name>` | Named migration | Development |
+| `prisma migrate deploy` | Apply pending migrations | Production/CI |
+| `prisma migrate reset` | Drop database, re-apply all migrations + seed | Development |
+| `prisma migrate status` | Show pending migrations | Any |
+| `prisma db push` | Push schema without migration file | Prototyping only |
+
+### migrate dev vs db push
+
+| Feature | `migrate dev` | `db push` |
+|---|---|---|
+| Creates migration file | Yes | No |
+| Version-controlled | Yes | No |
+| Safe for production | Yes | No |
+| Handles data loss warnings | Yes | May silently drop data |
+| Use case | All real development | Quick prototyping, throwaway databases |
+
+**Rule**: Always use `migrate dev` once your schema is past prototyping phase. Never use `db push` in production.
+
+---
+
+## Migration File Structure
+
+```
+prisma/
+  migrations/
+    20240115103000_init/
+      migration.sql
+    20240116140000_add_user_bio/
+      migration.sql
+    20240118090000_add_post_status/
+      migration.sql
+    migration_lock.toml          # Locks provider (postgresql)
+  schema.prisma
+  seed.ts
+```
+
+### Generated SQL Example
+
+```sql
+-- prisma/migrations/20240116140000_add_user_bio/migration.sql
+-- AlterTable
+ALTER TABLE "users" ADD COLUMN "bio" TEXT;
+```
+
+### Naming Convention
+
+```bash
+# Format: descriptive verb + subject
+pnpm prisma migrate dev --name init
+pnpm prisma migrate dev --name add_user_bio
+pnpm prisma migrate dev --name add_post_status_index
+pnpm prisma migrate dev --name create_comments_table
+pnpm prisma migrate dev --name make_email_unique
+pnpm prisma migrate dev --name remove_legacy_fields
+```
+
+---
+
+## Zero-Downtime Migration Patterns
+
+### Adding a Column
+
+```prisma
+// Safe: new nullable column with no default
+model User {
+  // existing fields...
+  bio String? @map("bio")  // New field - nullable, no data migration needed
+}
+```
+
+```bash
+pnpm prisma migrate dev --name add_user_bio
+```
+
+### Adding a Required Column (Two-Step)
+
+```
+# Step 1: Add as nullable, deploy code that writes to it
+model User {
+  phoneNumber String? @map("phone_number")
+}
+
+# Step 2: After backfilling, make required
+model User {
+  phoneNumber String @map("phone_number")
+}
+```
+
+```typescript
+// Backfill script (run between step 1 and step 2)
+// scripts/backfill-phone.ts
+import { prisma } from "../src/lib/prisma";
+
+async function backfill() {
+  const batchSize = 1000;
+  let processed = 0;
+
+  while (true) {
+    const users = await prisma.user.findMany({
+      where: { phoneNumber: null },
+      take: batchSize,
+      select: { id: true },
+    });
+
+    if (users.length === 0) break;
+
+    await prisma.user.updateMany({
+      where: { id: { in: users.map((u) => u.id) } },
+      data: { phoneNumber: "PENDING" },
+    });
+
+    processed += users.length;
+    console.log(`Backfilled ${processed} users`);
+  }
+}
+
+backfill();
+```
+
+### Renaming a Column (Three-Step)
+
+```
+# Step 1: Add new column, deploy code that writes to both
+# Step 2: Backfill new column, deploy code that reads from new column
+# Step 3: Remove old column
+```
+
+**Rule**: Never rename a column in a single migration. The running application will break between deploy and restart.
+
+### Adding an Index
+
+```prisma
+model Post {
+  // ...
+  @@index([authorId, status])
+}
+```
+
+For large tables, consider creating the index concurrently by editing the generated SQL:
+
+```sql
+-- Edit the migration.sql before applying
+CREATE INDEX CONCURRENTLY "Post_authorId_status_idx" ON "posts" ("author_id", "status");
+```
+
+**Note**: `CONCURRENTLY` only works in PostgreSQL and cannot run inside a transaction. Edit the migration SQL manually.
+
+---
+
+## Seed Data
+
+### Seed Script
+
+```typescript
+// prisma/seed.ts
+import { PrismaClient, UserRole } from "@prisma/client";
+import { hash } from "bcrypt";
+
+const prisma = new PrismaClient();
+
+async function main() {
+  // Idempotent: use upsert to avoid duplicates on re-run
+  const admin = await prisma.user.upsert({
+    where: { email: "admin@example.com" },
+    update: {},
+    create: {
+      email: "admin@example.com",
+      name: "Admin User",
+      hashedPassword: await hash("password123", 12),
+      role: UserRole.ADMIN,
+    },
+  });
+
+  console.log(`Seeded admin user: ${admin.id}`);
+
+  // Seed sample data for development
+  if (process.env.NODE_ENV !== "production") {
+    const posts = await Promise.all(
+      Array.from({ length: 10 }).map((_, i) =>
+        prisma.post.upsert({
+          where: { id: `seed-post-${i}` },
+          update: {},
+          create: {
+            id: `seed-post-${i}`,
+            title: `Sample Post ${i + 1}`,
+            body: `Content for post ${i + 1}`,
+            authorId: admin.id,
+            status: i % 3 === 0 ? "PUBLISHED" : "DRAFT",
+          },
+        })
+      )
+    );
+    console.log(`Seeded ${posts.length} posts`);
+  }
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  })
+  .finally(() => prisma.$disconnect());
+```
+
+### Configure Seed Command
+
+```json
+// package.json
+{
+  "prisma": {
+    "seed": "tsx prisma/seed.ts"
+  }
+}
+```
+
+```bash
+# Run seed
+pnpm prisma db seed
+
+# Reset + seed
+pnpm prisma migrate reset
+```
+
+---
+
+## Production Deployment
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/deploy.yml (relevant steps)
+- name: Apply migrations
+  run: pnpm prisma migrate deploy
+  env:
+    DATABASE_URL: ${{ secrets.DATABASE_URL }}
+
+- name: Deploy application
+  run: # deploy command
+```
+
+### Deployment Order
+
+1. Run `prisma migrate deploy` (applies pending migrations)
+2. Deploy new application code
+3. Verify health check passes
+
+**Rule**: Always run migrations before deploying new code. The old code must work with the new schema (see zero-downtime patterns above).
+
+### Rollback Strategy
+
+Prisma does not generate down migrations. Plan rollbacks manually:
+
+```bash
+# Option 1: Create a new "undo" migration
+pnpm prisma migrate dev --name revert_add_bio
+# Manually write the SQL to reverse the change
+
+# Option 2: Restore from database backup (last resort)
+```
+
+**Best practice**: Design migrations to be forward-only. If adding a column breaks things, the code should handle both states.
+
+---
+
+## Testing Migrations
+
+### Test Against Clean Database
+
+```bash
+# Verify all migrations apply cleanly from scratch
+pnpm prisma migrate reset --force
+pnpm prisma migrate deploy
+```
+
+### CI Migration Check
+
+```bash
+# In CI, verify no pending migrations exist in development
+pnpm prisma migrate diff --from-schema-datamodel prisma/schema.prisma --to-migrations prisma/migrations --exit-code
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| `db push` in production | No migration history, data loss risk | Always use `migrate deploy` |
+| Editing deployed migrations | Breaks migration checksums | Create new migrations to fix issues |
+| Adding NOT NULL without default | Breaks existing rows | Add nullable first, backfill, then constrain |
+| Single-step column rename | Running code breaks immediately | Three-step: add, migrate, remove |
+| No seed script | Manual data setup for every developer | Maintain `prisma/seed.ts` |
+| Skipping CI migration check | Schema drift between environments | Check migration status in CI |
+
+---
+
+_Migrations are deployments. Treat them with the same care: test them, version them, and always have a rollback plan._

package/framework/stacks/nextjs/models.md

@@ -0,0 +1,362 @@
+# Prisma Schema Design
+
+Best practices for Prisma schema definition, naming conventions, relations, and type-safe validation.
+
+---
+
+## Philosophy
+
+- **Schema is the source of truth**: Database structure defined in `schema.prisma`, validated by Zod
+- **Database enforces integrity**: Constraints live in the schema, not just application code
+- **Generated types everywhere**: Prisma Client types flow from schema to UI
+- **Thin models, rich services**: Business logic belongs in service functions, not in the schema
+
+---
+
+## Schema Configuration
+
+```prisma
+// prisma/schema.prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+---
+
+## Model Definition
+
+### Complete Example
+
+```prisma
+model User {
+  id             String    @id @default(cuid())
+  email          String    @unique
+  name           String
+  hashedPassword String    @map("hashed_password")
+  bio            String?
+  avatarUrl      String?   @map("avatar_url")
+  role           UserRole  @default(MEMBER)
+  isActive       Boolean   @default(true) @map("is_active")
+  lastLoginAt    DateTime? @map("last_login_at")
+  createdAt      DateTime  @default(now()) @map("created_at")
+  updatedAt      DateTime  @updatedAt @map("updated_at")
+
+  // Relations
+  posts    Post[]
+  accounts Account[]
+  sessions Session[]
+
+  @@map("users")
+}
+```
+
+### Naming Conventions
+
+| Entity | Convention | Example |
+|---|---|---|
+| Model name | PascalCase singular | `User`, `PostTag` |
+| Field name | camelCase | `createdAt`, `hashedPassword` |
+| Table name | snake_case plural via `@@map` | `@@map("users")` |
+| Column name | snake_case via `@map` | `@map("hashed_password")` |
+| Relation field | camelCase, matches related model | `posts`, `author` |
+| Enum name | PascalCase | `UserRole`, `PostStatus` |
+| Enum values | UPPER_SNAKE_CASE | `ADMIN`, `DRAFT` |
+
+**Why `@map`**: Prisma field names stay camelCase for TypeScript ergonomics while database columns use snake_case (SQL convention).
+
+---
+
+## Field Patterns
+
+### IDs
+
+```prisma
+// CUID (default recommendation)
+id String @id @default(cuid())
+
+// UUID
+id String @id @default(uuid())
+
+// Auto-increment (avoid for distributed systems)
+id Int @id @default(autoincrement())
+```
+
+**Decision**: Use `cuid()` by default. Non-sequential, URL-safe, and collision-resistant.
+
+### Timestamps
+
+```prisma
+// Every model gets these. No exceptions.
+createdAt DateTime @default(now()) @map("created_at")
+updatedAt DateTime @updatedAt @map("updated_at")
+```
+
+### Soft Deletes
+
+```prisma
+model Post {
+  // ... other fields
+  deletedAt DateTime? @map("deleted_at")
+
+  @@index([deletedAt])
+  @@map("posts")
+}
+```
+
+```typescript
+// Querying with soft deletes
+const activePosts = await prisma.post.findMany({
+  where: { deletedAt: null },
+});
+
+// Soft delete operation
+await prisma.post.update({
+  where: { id },
+  data: { deletedAt: new Date() },
+});
+```
+
+### Optional vs Required
+
+```prisma
+// Required (non-null) - field must always have a value
+name    String
+
+// Optional (nullable) - use ? suffix
+bio     String?
+
+// Required with default - automatically set if not provided
+role    UserRole @default(MEMBER)
+```
+
+**Rule**: Default to required. Only make fields optional when null has genuine meaning (e.g., "not yet set" vs "empty string").
+
+---
+
+## Enums
+
+```prisma
+enum UserRole {
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+enum PostStatus {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+model Post {
+  status PostStatus @default(DRAFT)
+  // ...
+}
+```
+
+### When to Use Enums vs Strings
+
+| Approach | When to Use |
+|---|---|
+| Prisma enum | Fixed set of values that rarely changes |
+| String field | Values that change often, user-defined categories |
+
+**Note**: Adding a value to a Prisma enum requires a migration. For frequently changing sets, use a string field with Zod validation.
+
+---
+
+## Relations
+
+### One-to-Many
+
+```prisma
+model User {
+  id    String @id @default(cuid())
+  posts Post[]
+
+  @@map("users")
+}
+
+model Post {
+  id       String @id @default(cuid())
+  authorId String @map("author_id")
+  author   User   @relation(fields: [authorId], references: [id], onDelete: Cascade)
+
+  @@index([authorId])
+  @@map("posts")
+}
+```
+
+### One-to-One
+
+```prisma
+model User {
+  id      String   @id @default(cuid())
+  profile Profile?
+
+  @@map("users")
+}
+
+model Profile {
+  id     String @id @default(cuid())
+  userId String @unique @map("user_id")
+  user   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  bio    String?
+
+  @@map("profiles")
+}
+```
+
+### Many-to-Many (Explicit Join Table)
+
+```prisma
+model Post {
+  id   String    @id @default(cuid())
+  tags PostTag[]
+
+  @@map("posts")
+}
+
+model Tag {
+  id    String    @id @default(cuid())
+  name  String    @unique
+  posts PostTag[]
+
+  @@map("tags")
+}
+
+model PostTag {
+  postId    String   @map("post_id")
+  tagId     String   @map("tag_id")
+  createdAt DateTime @default(now()) @map("created_at")
+  post      Post     @relation(fields: [postId], references: [id], onDelete: Cascade)
+  tag       Tag      @relation(fields: [tagId], references: [id], onDelete: Cascade)
+
+  @@id([postId, tagId])
+  @@map("post_tags")
+}
+```
+
+**Rule**: Always use explicit join tables over Prisma's implicit many-to-many. Explicit tables support additional fields (timestamps, ordering) and are easier to query.
+
+### Cascade Behaviors
+
+| Behavior | When to Use |
+|---|---|
+| `Cascade` | Child cannot exist without parent (comments on post) |
+| `SetNull` | Child can exist independently (optional foreign key) |
+| `Restrict` | Prevent deleting parent with existing children |
+| `NoAction` | Database-level, similar to Restrict |
+
+---
+
+## Indexes
+
+```prisma
+model Post {
+  id        String     @id @default(cuid())
+  authorId  String     @map("author_id")
+  status    PostStatus @default(DRAFT)
+  slug      String
+  createdAt DateTime   @default(now()) @map("created_at")
+
+  // Single-column index
+  @@index([authorId])
+
+  // Composite index (query pattern: "posts by author filtered by status")
+  @@index([authorId, status])
+
+  // Unique composite (slug unique per author)
+  @@unique([authorId, slug])
+
+  @@map("posts")
+}
+```
+
+### Indexing Rules
+
+- Always index foreign key columns
+- Add composite indexes for frequent multi-column queries
+- Use unique constraints for business uniqueness rules
+- Do not over-index; each index slows writes
+
+---
+
+## JSON Fields
+
+```prisma
+model User {
+  id          String @id @default(cuid())
+  preferences Json   @default("{}")
+
+  @@map("users")
+}
+```
+
+```typescript
+// Type-safe access with Zod
+import { z } from "zod";
+
+const preferencesSchema = z.object({
+  theme: z.enum(["light", "dark"]).default("light"),
+  emailNotifications: z.boolean().default(true),
+  language: z.string().default("en"),
+});
+
+type UserPreferences = z.infer<typeof preferencesSchema>;
+
+function getPreferences(raw: unknown): UserPreferences {
+  return preferencesSchema.parse(raw);
+}
+```
+
+**Warning**: JSON fields bypass Prisma's type system. Always validate with Zod when reading.
+
+---
+
+## Zod Validation Schemas
+
+### Paired with Prisma Models
+
+```typescript
+// lib/validations/user.ts
+import { z } from "zod";
+
+export const createUserSchema = z.object({
+  email: z.string().email("Invalid email address"),
+  name: z.string().min(1, "Name is required").max(255),
+  password: z.string().min(8, "Password must be at least 8 characters"),
+});
+
+export const updateUserSchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  bio: z.string().max(500).optional(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type UpdateUserInput = z.infer<typeof updateUserSchema>;
+```
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Correct Approach |
+|---|---|---|
+| Implicit many-to-many | Cannot add fields to join table later | Explicit join model with `@@id` |
+| No `@map` / `@@map` | Inconsistent naming across TypeScript and SQL | Map camelCase fields to snake_case columns |
+| Missing indexes on foreign keys | Slow joins and lookups | `@@index` on every foreign key |
+| Business logic in schema | Prisma schema is declarative only | Put logic in service functions |
+| `Int` IDs for distributed systems | Collisions across replicas | Use `cuid()` or `uuid()` |
+| No timestamps on models | Cannot debug or audit data | Always add `createdAt` and `updatedAt` |
+| Storing computed values | Gets out of sync | Compute at query time or use database views |
+
+---
+
+_The schema defines structure and integrity. Validation belongs in Zod. Business rules belong in services._