zilmate 1.7.8 → 1.8.1

package/.agents/skills/neon-drizzle/guides/existing-project.md

@@ -0,0 +1,398 @@
+# Existing Project Integration
+
+> **Complete Walkthrough**: This is a self-contained, step-by-step guide with its own numbered phases (Phase 1-8).
+> Follow each phase in order to safely add Drizzle to your existing application.
+
+Guide for adding Drizzle ORM to an existing application with Neon.
+
+### Important:
+- Remember to run the neon-plugin:add-neon-docs skill with the parameter SKILL_NAME="neon-drizzle" after completing the guide.
+
+## Table of Contents
+
+- [Workflow Checklist](#workflow-checklist)
+- [Phase 1: Pre-Integration Check](#phase-1-pre-integration-check)
+- [Phase 2: Incremental Installation](#phase-2-incremental-installation)
+- [Phase 3: Configuration](#phase-3-configuration)
+- [Phase 4: Schema Strategy](#phase-4-schema-strategy)
+- [Phase 5: Migration Handling](#phase-5-migration-handling)
+- [Phase 6: Coexistence Patterns](#phase-6-coexistence-patterns)
+- [Phase 7: Verification](#phase-7-verification)
+- [Phase 8: Add Best Practices References](#phase-8-add-best-practices-references)
+
+---
+
+## Workflow Checklist
+
+When following this guide, I will track these high-level tasks:
+
+- [ ] Pre-integration check (detect existing ORMs, database schema, environment)
+- [ ] Install Drizzle dependencies without disrupting existing setup
+- [ ] Create isolated Drizzle configuration (separate from existing code)
+- [ ] Choose and implement schema strategy (new tables vs mirroring existing)
+- [ ] Handle migrations safely based on schema strategy
+- [ ] Set up coexistence patterns and gradual migration approach
+- [ ] Verify Drizzle integration without breaking existing functionality
+- [ ] Add Neon Drizzle best practices to project docs
+
+---
+
+## Phase 1: Pre-Integration Check
+
+Before adding Drizzle, check for conflicts:
+
+### 1.1. Check for Other ORMs
+
+```bash
+grep -E '"(prisma|typeorm|sequelize|mongoose)"' package.json
+```
+
+**If found:**
+- Consider migration strategy (coexistence vs replacement)
+- Document which tables use which ORM
+- Plan gradual migration if needed
+
+### 1.2. Check Database Schema
+
+Connect to your database and verify existing tables:
+```bash
+psql $DATABASE_URL -c "\dt"
+```
+
+**Important:** Note existing tables - Drizzle should not conflict with them.
+
+### 1.3. Check Environment Setup
+
+```bash
+ls .env .env.local .env.production
+grep DATABASE_URL .env*
+```
+
+**If DATABASE_URL exists:**
+- Verify connection string format is compatible with Neon (`postgresql://...`)
+- If it's a different database provider, you'll need to migrate or provision a Neon database
+
+**If DATABASE_URL does NOT exist:**
+Follow the database provisioning steps from `guides/new-project.md` Phase 3.1:
+1. List the projects using the neon MCP Server to check existing projects
+2. Create a new project using the neon MCP Server if needed
+3. Get the connection string using the neon MCP Server
+4. Write to appropriate environment file (.env.local for Next.js, .env for others)
+5. Add environment file to .gitignore
+
+## Phase 2: Incremental Installation
+
+Add Drizzle without disrupting existing setup:
+
+### 2.1. Install Dependencies
+
+**For Vercel/Edge:**
+```bash
+[package-manager] add drizzle-orm @neondatabase/serverless
+[package-manager] add -D drizzle-kit dotenv
+```
+
+**For Node.js:**
+```bash
+[package-manager] add drizzle-orm @neondatabase/serverless ws
+[package-manager] add -D drizzle-kit dotenv @types/ws
+```
+
+### 2.2. Create Isolated Drizzle Directory
+
+Keep Drizzle separate from existing code:
+```bash
+mkdir -p src/drizzle
+```
+
+Structure:
+```
+src/drizzle/
+├── index.ts      # Connection
+├── schema.ts     # New schemas only
+└── migrations/   # Drizzle migrations
+```
+
+## Phase 3: Configuration
+
+### 3.1. Create Drizzle Config
+
+Create `drizzle.config.ts` with explicit environment loading:
+
+**CRITICAL:** The `config({ path: '...' })` must match your environment file name.
+
+**For Next.js (using .env.local):**
+```typescript
+import { defineConfig } from 'drizzle-kit';
+import { config } from 'dotenv';
+
+// Load .env.local explicitly
+config({ path: '.env.local' });
+
+export default defineConfig({
+  schema: './src/drizzle/schema.ts',
+  out: './src/drizzle/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+```
+
+**For other projects (using .env):**
+```typescript
+import { defineConfig } from 'drizzle-kit';
+import { config } from 'dotenv';
+
+// Load .env explicitly
+config({ path: '.env' });
+
+export default defineConfig({
+  schema: './src/drizzle/schema.ts',
+  out: './src/drizzle/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+```
+
+**Notes:**
+- Point schema and migrations to `src/drizzle/` to avoid conflicts with existing code
+- Explicit dotenv path prevents "url: undefined" errors during migrations
+
+### 3.2. Create Connection
+
+`src/drizzle/index.ts` - Choose adapter based on environment (see `references/adapters.md`):
+
+**HTTP (Vercel/Edge):**
+```typescript
+import { drizzle } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+
+const sql = neon(process.env.DATABASE_URL!);
+export const drizzleDb = drizzle(sql);
+```
+
+**WebSocket (Node.js):**
+```typescript
+import { drizzle } from 'drizzle-orm/neon-serverless';
+import { Pool, neonConfig } from '@neondatabase/serverless';
+import ws from 'ws';
+
+neonConfig.webSocketConstructor = ws;
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+export const drizzleDb = drizzle(pool);
+```
+
+**Important:** Name export as `drizzleDb` to avoid conflicts with existing `db` exports.
+
+## Phase 4: Schema Strategy
+
+Choose integration approach:
+
+### 4.1. Option A: New Tables Only
+
+Create schemas for new features only, leave existing tables alone:
+
+`src/drizzle/schema.ts`:
+```typescript
+import { pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';
+
+export const newFeatureTable = pgTable('new_feature', {
+  id: serial('id').primaryKey(),
+  data: text('data').notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+```
+
+**Pros:**
+- No migration of existing data
+- Zero risk to current functionality
+- Gradual adoption
+
+**Cons:**
+- Mixed query patterns (Drizzle + existing ORM)
+- Two connection patterns in codebase
+
+### 4.2. Option B: Mirror Existing Tables
+
+Define schemas for existing tables to gradually migrate queries:
+
+```typescript
+import { pgTable, serial, varchar, timestamp } from 'drizzle-orm/pg-core';
+
+export const existingUsers = pgTable('users', {
+  id: serial('id').primaryKey(),
+  email: varchar('email', { length: 255 }).notNull(),
+  name: varchar('name', { length: 255 }),
+  createdAt: timestamp('created_at'),
+});
+```
+
+**Pros:**
+- Can query existing data with Drizzle
+- Gradually replace old ORM queries
+- Type-safe access to existing tables
+
+**Cons:**
+- Must match existing schema exactly
+- Requires careful migration strategy
+
+### 4.3. Recommended: Hybrid Approach
+
+1. Start with Option A (new tables only)
+2. Once comfortable, add schemas for frequently-queried existing tables (Option B)
+3. Gradually migrate queries from old ORM to Drizzle
+4. Eventually remove old ORM
+
+## Phase 5: Migration Handling
+
+### 5.1. For New Tables
+
+Generate and run migrations normally:
+```bash
+[package-manager] drizzle-kit generate
+export DATABASE_URL="$(grep DATABASE_URL .env.local | cut -d '=' -f2)" && \
+[package-manager] drizzle-kit migrate
+```
+
+### 5.2. For Existing Tables
+
+**Do NOT run migrations** - tables already exist!
+
+Instead, use Drizzle schemas for querying only:
+```typescript
+import { drizzleDb } from './drizzle';
+import { existingUsers } from './drizzle/schema';
+
+const users = await drizzleDb.select().from(existingUsers);
+```
+
+### 5.3. Mixed Scenario
+
+If you have both new and existing tables:
+1. Define all schemas in `schema.ts`
+2. Run `drizzle-kit generate`
+3. **Manually edit** generated migration to remove SQL for existing tables
+4. Apply migration
+
+See `references/migrations.md` for advanced patterns.
+
+### 5.4. Add Migration Scripts
+
+Add these convenience scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  }
+}
+```
+
+**Usage:**
+```bash
+npm run db:generate  # Generate migrations from schema changes
+npm run db:migrate   # Apply pending migrations
+npm run db:push      # Push schema directly (dev only)
+npm run db:studio    # Open Drizzle Studio
+```
+
+**Note:** Replace `npm run` with your package manager's equivalent (`pnpm`, `yarn`, `bun`).
+
+## Phase 6: Coexistence Patterns
+
+### 6.1. Naming Conventions
+
+Keep clear separation:
+```typescript
+import { db as prismaDb } from './lib/prisma';
+import { drizzleDb } from './drizzle';
+
+const prismaUsers = await prismaDb.user.findMany();
+const drizzleFeatures = await drizzleDb.select().from(newFeatureTable);
+```
+
+### 6.2. Gradual Migration
+
+**Step 1:** New features use Drizzle
+```typescript
+async function createFeature(data: NewFeatureInput) {
+  return drizzleDb.insert(newFeatureTable).values(data).returning();
+}
+```
+
+**Step 2:** Migrate read queries (safe, no data changes)
+```typescript
+async function getUsers() {
+  return drizzleDb.select().from(existingUsers);
+}
+```
+
+**Step 3:** Migrate write queries (after thorough testing)
+```typescript
+async function updateUser(id: number, data: UserUpdate) {
+  return drizzleDb.update(existingUsers)
+    .set(data)
+    .where(eq(existingUsers.id, id));
+}
+```
+
+**Step 4:** Remove old ORM once all queries migrated
+
+## Phase 7: Verification
+
+Test integration without breaking existing functionality:
+
+### 7.1. Test New Tables
+
+```typescript
+import { drizzleDb } from './drizzle';
+import { newFeatureTable } from './drizzle/schema';
+
+const result = await drizzleDb.insert(newFeatureTable)
+  .values({ data: 'test' })
+  .returning();
+
+console.log('New table works:', result);
+```
+
+### 7.2. Test Existing Tables (if mirrored)
+
+```typescript
+import { drizzleDb } from './drizzle';
+import { existingUsers } from './drizzle/schema';
+
+const users = await drizzleDb.select().from(existingUsers);
+console.log('Existing table accessible:', users);
+```
+
+### 7.3. Verify Old ORM Still Works
+
+```typescript
+import { db as oldDb } from './lib/your-orm';
+
+const oldQuery = await oldDb.users.findMany();
+console.log('Old ORM still works:', oldQuery);
+```
+
+## Phase 8: Add Best Practices References
+
+Before executing the add-neon-docs skill, provide a summary of everything that has been done:
+
+"✅ ... Drizzle integration is complete! Now adding documentation references..."
+
+Then execute the neon-plugin:add-neon-docs skill with the parameter SKILL_NAME="neon-drizzle"
+
+This will add reference links to Neon + Drizzle best practices documentation in your project's AI documentation file, helping AI assistants provide better guidance in future conversations.
+
+---
+
+## ✅ Integration Complete!
+
+Your Drizzle integration with the existing project is ready to use.
+

package/.agents/skills/neon-drizzle/guides/new-project.md

@@ -0,0 +1,312 @@
+# New Project Setup
+
+> **Complete Walkthrough**: This is a self-contained, step-by-step guide with its own numbered phases (Phase 1-6).
+> Follow each phase in order for a full Drizzle + Neon setup from scratch.
+
+Complete guide for setting up Drizzle ORM with Neon from scratch.
+
+### Important:
+- Remember to run the neon-plugin:add-neon-docs skill with the parameter SKILL_NAME="neon-drizzle" after completing the guide.
+
+## Table of Contents
+
+- [New Project Setup](#new-project-setup)
+    - [Important:](#important)
+  - [Table of Contents](#table-of-contents)
+  - [Workflow Checklist](#workflow-checklist)
+  - [Phase 1: Context Detection](#phase-1-context-detection)
+  - [Phase 2: Installation](#phase-2-installation)
+  - [Phase 3: Configuration](#phase-3-configuration)
+    - [3.1. Neon Database Provisioning \& Environment File](#31-neon-database-provisioning--environment-file)
+    - [3.2. Drizzle Config](#32-drizzle-config)
+    - [3.3. Database Connection](#33-database-connection)
+  - [Phase 4: Schema Generation](#phase-4-schema-generation)
+    - [4.1. Common Patterns](#41-common-patterns)
+  - [Phase 5: Migrations](#phase-5-migrations)
+    - [5.1. Generate Migration](#51-generate-migration)
+    - [5.2. Apply Migration](#52-apply-migration)
+    - [5.3. Add Migration Scripts](#53-add-migration-scripts)
+    - [5.4. If Migration Fails](#54-if-migration-fails)
+  - [Phase 6: Add Best Practices References](#phase-6-add-best-practices-references)
+  - [✅ Setup Complete!](#-setup-complete)
+
+---
+
+## Workflow Checklist
+
+When following this guide, I will track these high-level tasks:
+
+- [ ] Detect project context (package manager, framework, existing setup)
+- [ ] Install Drizzle dependencies based on deployment target
+- [ ] Provision Neon database (list projects, create if needed, get connection string)
+- [ ] Write connection string to environment file and verify
+- [ ] Create Drizzle configuration files (drizzle.config.ts, db connection)
+- [ ] Generate schema based on app type
+- [ ] Run and verify migrations
+- [ ] Add Neon Drizzle best practices to project docs
+
+---
+
+## Phase 1: Context Detection
+
+Auto-detect project context:
+
+**Check Package Manager:**
+```bash
+ls package-lock.json  # → npm
+ls bun.lockb          # → bun
+ls pnpm-lock.yaml     # → pnpm
+ls yarn.lock          # → yarn
+```
+
+**Check Framework:**
+```bash
+grep '"next"' package.json      # → Next.js
+grep '"express"' package.json   # → Express
+grep '"vite"' package.json      # → Vite
+```
+
+**Check Existing Setup:**
+```bash
+ls drizzle.config.ts   # Already configured?
+ls src/db/schema.ts    # Schema exists?
+```
+
+**Check Environment Files:**
+```bash
+ls .env .env.local .env.production
+```
+
+## Phase 2: Installation
+
+Based on detection, install dependencies:
+
+**For Vercel/Edge Environments (Next.js, Vite on Vercel):**
+```bash
+[package-manager] add drizzle-orm @neondatabase/serverless
+[package-manager] add -D drizzle-kit dotenv @vercel/node
+```
+
+**For Node.js Servers (Express, Fastify, standard Node):**
+```bash
+[package-manager] add drizzle-orm @neondatabase/serverless ws
+[package-manager] add -D drizzle-kit dotenv @types/ws
+```
+
+## Phase 3: Configuration
+
+Create configuration files in dependency order:
+
+### 3.1. Neon Database Provisioning & Environment File
+
+**Outcome**: A working `.env` or `.env.local` file with a real Neon connection string that the application can use immediately.
+
+Use MCP tools to list or create a Neon project and get its connection string. Write the actual credentials to the environment file (`.env.local` for Next.js, `.env` for other projects). Add the file to `.gitignore`.
+
+**Environment file format:**
+```bash
+DATABASE_URL=postgresql://user:password@host/database?sslmode=require
+```
+
+### 3.2. Drizzle Config
+
+Create `drizzle.config.ts` with explicit environment loading:
+
+**CRITICAL:** The `config({ path: '...' })` line must match the environment file from Step 3.1.
+
+**For Next.js (using .env.local):**
+```typescript
+import { defineConfig } from 'drizzle-kit';
+import { config } from 'dotenv';
+
+// Load .env.local explicitly
+config({ path: '.env.local' });
+
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  out: './src/db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+```
+
+**For other projects (using .env):**
+```typescript
+import { defineConfig } from 'drizzle-kit';
+import { config } from 'dotenv';
+
+// Load .env explicitly
+config({ path: '.env' });
+
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  out: './src/db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});
+```
+
+**Why this matters:**
+- Without explicit `config({ path: '...' })`, drizzle-kit may not load environment variables
+- This prevents "url: undefined" errors during migrations
+- The path must match your environment file name from Phase 3.1
+
+### 3.3. Database Connection
+
+Create `src/db/index.ts` with appropriate adapter (see `references/adapters.md` for decision guide):
+
+**For Vercel/Edge:**
+```typescript
+import { drizzle } from 'drizzle-orm/neon-http';
+import { neon } from '@neondatabase/serverless';
+
+const sql = neon(process.env.DATABASE_URL!);
+export const db = drizzle(sql);
+```
+
+**For Node.js:**
+```typescript
+import { drizzle } from 'drizzle-orm/neon-serverless';
+import { Pool, neonConfig } from '@neondatabase/serverless';
+import ws from 'ws';
+
+neonConfig.webSocketConstructor = ws;
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+export const db = drizzle(pool);
+```
+
+See `templates/db-http.ts` and `templates/db-websocket.ts` for complete examples.
+
+## Phase 4: Schema Generation
+
+Based on app type, create appropriate schema:
+
+### 4.1. Common Patterns
+
+**Todo App:**
+```typescript
+import { pgTable, serial, text, boolean, timestamp, varchar } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  name: varchar('name', { length: 255 }).notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+
+export const todos = pgTable('todos', {
+  id: serial('id').primaryKey(),
+  userId: serial('user_id').notNull().references(() => users.id),
+  title: text('title').notNull(),
+  completed: boolean('completed').default(false),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+```
+
+**Blog App:**
+```typescript
+import { pgTable, serial, text, timestamp, varchar, index } from 'drizzle-orm/pg-core';
+import { relations } from 'drizzle-orm';
+
+export const users = pgTable('users', {
+  id: serial('id').primaryKey(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  name: varchar('name', { length: 255 }).notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+});
+
+export const posts = pgTable('posts', {
+  id: serial('id').primaryKey(),
+  userId: serial('user_id').notNull().references(() => users.id),
+  title: text('title').notNull(),
+  content: text('content').notNull(),
+  createdAt: timestamp('created_at').defaultNow(),
+}, (table) => ({
+  userIdIdx: index('posts_user_id_idx').on(table.userId),
+}));
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, {
+    fields: [posts.userId],
+    references: [users.id],
+  }),
+}));
+```
+
+See `templates/schema-example.ts` for more complex examples.
+
+## Phase 5: Migrations
+
+Run migrations with proper error handling:
+
+### 5.1. Generate Migration
+
+```bash
+[package-manager] drizzle-kit generate
+```
+
+This creates SQL files in `src/db/migrations/`.
+
+### 5.2. Apply Migration
+
+**Recommended approach (explicit env loading):**
+```bash
+export DATABASE_URL="$(grep DATABASE_URL .env.local | cut -d '=' -f2)" && \
+[package-manager] drizzle-kit migrate
+```
+
+**Why this works:** Ensures `DATABASE_URL` is available, preventing "url: undefined" errors.
+
+### 5.3. Add Migration Scripts
+
+Add these convenience scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  }
+}
+```
+
+**Usage:**
+```bash
+npm run db:generate  # Generate migrations from schema changes
+npm run db:migrate   # Apply pending migrations
+npm run db:push      # Push schema directly (dev only)
+npm run db:studio    # Open Drizzle Studio
+```
+
+**Note:** Replace `npm run` with your package manager's equivalent (`pnpm`, `yarn`, `bun`).
+
+### 5.4. If Migration Fails
+
+See `guides/troubleshooting.md` for common issues and fixes.
+
+Also reference `references/migrations.md` for deep dive on migration patterns.
+
+## Phase 6: Add Best Practices References
+
+Before executing the add-neon-docs skill, provide a summary of everything that has been done:
+
+"✅ ... Drizzle integration is complete! Now adding documentation references..."
+
+Then execute the neon-plugin:add-neon-docs skill with the parameter SKILL_NAME="neon-drizzle"
+
+This will add reference links to Neon + Drizzle best practices documentation in your project's AI documentation file, helping AI assistants provide better guidance in future conversations.
+
+## ✅ Setup Complete!
+
+Your Drizzle + Neon integration is ready to use.
+