@electric-agent/agent 1.0.0

package/playbooks/electric-app-guardrails/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: electric-app-guardrails
+description: Project-specific guardrails for drizzle-zod integration, parseDates, ClientOnly, testing patterns, and hallucination guard. Read this FIRST before coding.
+triggers:
+  - zod-schemas
+  - drizzle-zod
+  - parseDates
+  - ClientOnly
+  - testing
+  - smoke test
+  - hallucination
+  - lucide
+  - icons
+---
+
+# Project-Specific Guardrails
+
+Patterns NOT covered by external playbooks. Read playbooks for collections, live-queries, mutations, schemas, and Electric quickstart patterns.
+
+## Drizzle-Zod Integration (CRITICAL)
+
+**Import `z` from `"zod/v4"`** (NOT `"zod"`) — drizzle-zod 0.8.x uses Zod v4 internals. The v4 runtime rejects v3-style overrides with "Invalid element: expected a Zod schema".
+
+**Always override timestamp columns** with `z.union([z.date(), z.string()]).default(() => new Date())` — Electric streams dates as ISO strings, but `createSelectSchema` generates `z.date()` which only accepts Date objects. The `.default()` is critical: it makes timestamps omittable during `collection.insert()` (the DB sets them server-side), while still accepting them when present from Electric sync. Without this, `collection.insert()` throws `SchemaValidationError` on `created_at`/`updated_at`.
+
+**Do NOT use `z.coerce.date()`** — creates ZodEffects that TanStack DB's schema introspection rejects.
+
+```typescript
+// src/db/zod-schemas.ts
+import { createSelectSchema, createInsertSchema } from "drizzle-zod"
+import { z } from "zod/v4"
+import { todos } from "./schema"
+
+const dateOrString = z.union([z.date(), z.string()]).default(() => new Date())
+
+export const todoSelectSchema = createSelectSchema(todos, {
+  created_at: dateOrString,
+  updated_at: dateOrString,
+})
+export const todoInsertSchema = createInsertSchema(todos, {
+  created_at: dateOrString.optional(),
+  updated_at: dateOrString.optional(),
+})
+```
+
+**Use `selectSchema` as the collection schema** — it has defaults for timestamps so `collection.insert()` works without them, and validates fully populated rows from Electric sync.
+
+## parseDates Utility (CRITICAL)
+
+Mutation routes MUST wrap `request.json()` with `parseDates()` — JSON serialization turns Date objects into ISO strings, and Drizzle's timestamp columns crash on strings.
+```typescript
+import { parseDates } from "@/db/utils"
+const data = parseDates(await request.json())
+```
+
+## Mutation PUT/PATCH Handlers (CRITICAL)
+
+**Always destructure out timestamp columns** before spreading into `.set()`. Electric streams timestamps as Postgres-format strings (`"2024-01-01 00:00:00+00"` — space separator, not ISO `T`). `parseDates` only matches ISO format, so these pass through as raw strings. Drizzle's `PgTimestamp.mapToDriverValue` calls `.toISOString()` on them → `TypeError: value.toISOString is not a function`.
+
+```typescript
+// WRONG — created_at leaks into .set() as a string, Drizzle crashes
+const { id, ...rest } = body
+await tx.update(todos).set({ ...rest, updated_at: new Date() })
+
+// RIGHT — strip timestamps, only spread user-editable fields
+const { id, created_at: _, updated_at: __, ...fields } = body
+await tx.update(todos).set({ ...fields, updated_at: new Date() })
+```
+
+## ClientOnly Wrapper
+
+Components using `useLiveQuery` that must render from `__root.tsx` need `ClientOnly`:
+```typescript
+import { ClientOnly } from "../components/ClientOnly"
+<ClientOnly fallback={<Box style={{ width: 240 }} />}>
+  {() => <Sidebar />}
+</ClientOnly>
+```
+`ClientOnly` is provided by the scaffold. **NEVER render useLiveQuery components directly in `__root.tsx`** — crashes with `Missing getServerSnapshot`.
+
+## Collection shapeOptions URL (CRITICAL)
+
+`shapeOptions.url` MUST be an absolute URL — Electric's `ShapeStream` calls `new URL(url)` with no base, which throws on relative paths like `"/api/todos"`.
+
+```typescript
+// WRONG — relative URL, ShapeStream throws "Invalid URL"
+shapeOptions: { url: "/api/todos" }
+
+// RIGHT — absolute URL with SSR-safe fallback
+shapeOptions: {
+  url: new URL(
+    "/api/todos",
+    typeof window !== "undefined" ? window.location.origin : "http://localhost:5174",
+  ).toString(),
+}
+```
+
+## API Route Pattern (CRITICAL)
+
+Use `createFileRoute` from `@tanstack/react-router` with `server.handlers`. Do NOT use `createAPIFileRoute` or `createServerFileRoute` — those do not exist in the installed packages.
+
+### Electric Shape Proxy Route (`src/routes/api/<tablename>.ts`)
+```typescript
+import { createFileRoute } from "@tanstack/react-router"
+import { proxyElectricRequest } from "@/lib/electric-proxy"
+
+export const Route = createFileRoute("/api/todos")({
+  // @ts-expect-error – server.handlers types lag behind runtime support
+  server: {
+    handlers: {
+      GET: async ({ request }: { request: Request }) => {
+        return proxyElectricRequest(request, "todos")
+      },
+    },
+  },
+})
+```
+
+### Mutation Route (`src/routes/api/mutations/<tablename>.ts`)
+```typescript
+import { createFileRoute } from "@tanstack/react-router"
+import { eq } from "drizzle-orm"
+import { db } from "@/db"
+import { todos } from "@/db/schema"
+import { generateTxId, parseDates } from "@/db/utils"
+
+export const Route = createFileRoute("/api/mutations/todos")({
+  // @ts-expect-error – server.handlers types lag behind runtime support
+  server: {
+    handlers: {
+      POST: async ({ request }: { request: Request }) => {
+        const body = parseDates(await request.json())
+        const txid = await db.transaction(async (tx) => {
+          await tx.insert(todos).values(body)
+          return generateTxId(tx)
+        })
+        return new Response(JSON.stringify({ txid }), {
+          headers: { "Content-Type": "application/json" },
+        })
+      },
+      PUT: async ({ request }: { request: Request }) => {
+        const body = parseDates(await request.json())
+        const { id, created_at: _, updated_at: __, ...fields } = body
+        const txid = await db.transaction(async (tx) => {
+          await tx.update(todos).set({ ...fields, updated_at: new Date() }).where(eq(todos.id, id as string))
+          return generateTxId(tx)
+        })
+        return new Response(JSON.stringify({ txid }), {
+          headers: { "Content-Type": "application/json" },
+        })
+      },
+      DELETE: async ({ request }: { request: Request }) => {
+        const body = parseDates(await request.json())
+        const txid = await db.transaction(async (tx) => {
+          await tx.delete(todos).where(eq(todos.id, body.id as string))
+          return generateTxId(tx)
+        })
+        return new Response(JSON.stringify({ txid }), {
+          headers: { "Content-Type": "application/json" },
+        })
+      },
+    },
+  },
+})
+```
+
+### Route Naming Convention
+
+- `/api/<tablename>` — Electric shape proxy (GET only)
+- `/api/mutations/<tablename>` — Write mutations (POST/PUT/DELETE)
+
+## Icons
+
+Use `lucide-react` (already installed). Do NOT use `@radix-ui/react-icons` (not installed).
+```typescript
+import { Trash2, Plus, Check, X, Search } from "lucide-react"
+```
+
+## Drizzle Schema Conventions
+
+- UUID primary keys: `uuid().primaryKey().defaultRandom()`
+- Timestamps: `timestamp({ withTimezone: true })`
+- snake_case for SQL table/column names
+- Foreign keys: `.references(() => table.id, { onDelete: "cascade" })` — do NOT import `relations` from `drizzle-orm`
+- Every table needs REPLICA IDENTITY FULL (auto-applied by migration hook)
+- `src/server.ts` entry point is required
+- vite.config.ts must include `nitro()` plugin
+
+## Testing Patterns
+
+### File Structure
+```
+tests/
+├── helpers/
+│   └── schema-test-utils.ts    # generateValidRow, generateRowWithout (scaffold-provided)
+├── schema.test.ts              # Zod schema smoke tests — no Docker
+├── collections.test.ts         # Collection insert validation — no Docker
+└── integration/
+    └── data-flow.test.ts       # Drizzle insert + read back — requires Docker
+```
+
+### Schema Smoke Test
+```typescript
+import { generateValidRow, generateRowWithout } from "./helpers/schema-test-utils"
+import { todoSelectSchema } from "@/db/zod-schemas"
+
+describe("todo schema", () => {
+  it("accepts a complete row", () => {
+    expect(todoSelectSchema.safeParse(generateValidRow(todoSelectSchema)).success).toBe(true)
+  })
+  it("rejects without id", () => {
+    expect(todoSelectSchema.safeParse(generateRowWithout(todoSelectSchema, "id")).success).toBe(false)
+  })
+})
+```
+
+### JSON Round-Trip Test
+```typescript
+it("survives JSON round-trip", () => {
+  const row = generateValidRow(todoSelectSchema)
+  const serialized = JSON.parse(JSON.stringify(row))
+  const revived = parseDates(serialized)
+  expect(todoSelectSchema.safeParse(revived).success).toBe(true)
+})
+```
+
+### Testing Rules
+- **DO NOT** import collection files in smoke tests — collections connect to Electric on import
+- **DO NOT** import `@/db` in smoke tests — requires Postgres
+- **ONLY** import from `@/db/zod-schemas` and `@/db/schema` in smoke tests
+- **ALWAYS** test that removing `id`, `createdAt`, `updatedAt` causes validation failure
+- Use `generateValidRow(schema)` — never hand-write partial test data
+
+## Hallucination Guard
+
+| WRONG | RIGHT |
+|-------|-------|
+| `import { z } from "zod"` in zod-schemas | `import { z } from "zod/v4"` |
+| `createSelectSchema(todos)` without date overrides | Override ALL timestamps: `{ created_at: z.union([z.date(), z.string()]).default(() => new Date()) }` |
+| `z.union([z.date(), z.string()])` without `.default()` | Add `.default(() => new Date())` — required for `collection.insert()` to work without timestamps |
+| `z.coerce.date()` for timestamps | `z.union([z.date(), z.string()])` |
+| `import { createInsertSchema } from 'drizzle-orm/zod'` | `from 'drizzle-zod'` |
+| `import { drizzle } from 'drizzle-orm'` | `from 'drizzle-orm/postgres-js'` |
+| `import { X } from '@radix-ui/react-icons'` | `from 'lucide-react'` |
+| `import { relations } from "drizzle-orm"` | Use `.references()` on columns instead |
+| `const data = await request.json()` in mutations | `parseDates(await request.json())` |
+| `<Sidebar />` (useLiveQuery) in `__root.tsx` | `<ClientOnly>{() => <Sidebar />}</ClientOnly>` |
+| `import { todoCollection }` in smoke tests | Import from `@/db/zod-schemas` only |
+| `import { db } from "@/db"` in smoke tests | Only in integration tests |
+| Testing with `{ text: "foo" }` (partial) | `generateValidRow(schema)` |
+| `const { id, ...rest } = body` then `.set(rest)` in PUT | Destructure out `created_at`, `updated_at` before spreading |
+| `shapeOptions: { url: "/api/todos" }` (relative) | `url: new URL("/api/todos", typeof window !== "undefined" ? window.location.origin : "http://localhost:5174").toString()` |
+| `import { createAPIFileRoute } from '@tanstack/start/api'` | Does NOT exist — use `createFileRoute` from `@tanstack/react-router` with `server.handlers` |
+| `import { createServerFileRoute } from '@tanstack/start/server'` | Does NOT exist — use `createFileRoute` from `@tanstack/react-router` with `server.handlers` |
+| `createAPIFileRoute('/api/todos')` | `createFileRoute('/api/todos')({ server: { handlers: { GET: ... } } })` |

package/template/.env.example

@@ -0,0 +1,2 @@
+DATABASE_URL=postgresql://postgres:password@localhost:54321/electric
+ELECTRIC_URL=http://localhost:3000

package/template/Caddyfile

@@ -0,0 +1,11 @@
+http://localhost:5173 {
+	# Proxy Electric shape API
+	handle /v1/shape* {
+		reverse_proxy electric:3000
+	}
+
+	# Proxy everything else to the Vite dev server
+	handle {
+		reverse_proxy host.docker.internal:5174
+	}
+}

package/template/docker-compose.yml

@@ -0,0 +1,47 @@
+services:
+  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_DB: electric
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+    ports:
+      - "54321:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./postgres.conf:/etc/postgresql/postgresql.conf
+    command: postgres -c config_file=/etc/postgresql/postgresql.conf
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 2s
+      timeout: 5s
+      retries: 10
+
+  electric:
+    image: electricsql/electric:latest
+    environment:
+      DATABASE_URL: postgresql://postgres:password@postgres:5432/electric
+      ELECTRIC_INSECURE: "true"
+    ports:
+      - "3000:3000"
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  caddy:
+    image: caddy:2-alpine
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    ports:
+      - "5173:5173"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - electric
+
+volumes:
+  pgdata:
+  caddy_data:
+  caddy_config:

package/template/drizzle.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "drizzle-kit"
+
+if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is not set")
+
+export default defineConfig({
+	out: "./drizzle",
+	schema: "./src/db/schema.ts",
+	dialect: "postgresql",
+	dbCredentials: {
+		url: process.env.DATABASE_URL,
+	},
+})

package/template/postgres.conf

@@ -0,0 +1,4 @@
+listen_addresses = '*'
+wal_level = logical
+max_replication_slots = 10
+max_wal_senders = 10

package/template/src/components/ClientOnly.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from "react"
+import { useSyncExternalStore } from "react"
+
+const emptySubscribe = () => () => {}
+
+/**
+ * Renders children only on the client. During SSR, renders the fallback.
+ * Use this to wrap components that use useLiveQuery or collections
+ * when they need to be rendered from __root.tsx (which always SSRs).
+ *
+ * Uses useSyncExternalStore with getServerSnapshot=false so React
+ * correctly handles the server/client boundary without hydration mismatch.
+ */
+export function ClientOnly({
+	children,
+	fallback,
+}: {
+	children: () => ReactNode
+	fallback?: ReactNode
+}) {
+	const isClient = useSyncExternalStore(
+		emptySubscribe,
+		() => true,
+		() => false,
+	)
+	return isClient ? children() : (fallback ?? null)
+}

package/template/src/db/index.ts

@@ -0,0 +1,7 @@
+import { drizzle } from "drizzle-orm/postgres-js"
+import postgres from "postgres"
+import * as schema from "./schema"
+
+if (!process.env.DATABASE_URL) throw new Error("DATABASE_URL is not set")
+const client = postgres(process.env.DATABASE_URL)
+export const db = drizzle(client, { schema })

package/template/src/db/schema.ts

@@ -0,0 +1,14 @@
+// Drizzle schema — the single source of truth for your data model.
+// Define your tables here using pgTable(). The agent will fill this in.
+//
+// Example:
+// import { pgTable, uuid, text, boolean, timestamp } from "drizzle-orm/pg-core"
+//
+// export const todos = pgTable("todos", {
+//   id: uuid().primaryKey().defaultRandom(),
+//   text: text().notNull(),
+//   completed: boolean().notNull().default(false),
+//   createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+// })
+
+export {}

package/template/src/db/utils.ts

@@ -0,0 +1,31 @@
+import { sql } from "drizzle-orm"
+
+/**
+ * Get the current Postgres transaction ID. Used to correlate
+ * optimistic updates with server-side writes via Electric sync.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle transaction type varies by driver
+export async function generateTxId(tx: any): Promise<number> {
+	const result = await tx.execute(sql`SELECT pg_current_xact_id()::text as txid`)
+	const txid = result[0]?.txid
+	if (txid === undefined) throw new Error("Failed to get transaction ID")
+	return parseInt(txid as string, 10)
+}
+
+/**
+ * Convert ISO date strings back to Date objects after JSON deserialization.
+ * Use this in mutation routes: `const data = parseDates(await request.json())`
+ *
+ * When collections send data via fetch(), JSON.stringify turns Date objects
+ * into ISO strings. Drizzle's timestamp columns expect Date objects, so
+ * passing the raw JSON to db.insert() crashes with "toISOString is not a function".
+ */
+export function parseDates<T extends Record<string, unknown>>(obj: T): T {
+	const result = { ...obj }
+	for (const [key, value] of Object.entries(result)) {
+		if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+			;(result as Record<string, unknown>)[key] = new Date(value)
+		}
+	}
+	return result as T
+}

package/template/src/db/zod-schemas.ts

@@ -0,0 +1,14 @@
+// Zod schemas derived from Drizzle tables.
+// Never hand-write Zod schemas — always use createSelectSchema / createInsertSchema.
+//
+// Example:
+// import { createSelectSchema, createInsertSchema } from "drizzle-zod"
+// import { todos } from "./schema"
+//
+// export const todoSelectSchema = createSelectSchema(todos)
+// export const todoInsertSchema = createInsertSchema(todos)
+//
+// export type Todo = typeof todoSelectSchema._type
+// export type NewTodo = typeof todoInsertSchema._type
+
+export {}

package/template/src/lib/electric-proxy.ts

@@ -0,0 +1,59 @@
+/**
+ * Electric shape proxy helpers.
+ * Used by API routes to forward shape requests to the Electric service.
+ *
+ * Supports both local Electric (Docker) and Electric Cloud.
+ * For Electric Cloud, set these environment variables:
+ *   ELECTRIC_URL=https://api.electric-sql.cloud
+ *   ELECTRIC_SOURCE_ID=<your-source-id>
+ *   ELECTRIC_SECRET=<your-secret>
+ */
+
+export function prepareElectricUrl(request: Request, tableName: string): string {
+	const electricUrl = process.env.ELECTRIC_URL || "http://localhost:3000"
+	const url = new URL(`${electricUrl}/v1/shape`)
+
+	// Forward Electric-specific query parameters
+	const requestUrl = new URL(request.url)
+	for (const [key, value] of requestUrl.searchParams) {
+		url.searchParams.set(key, value)
+	}
+
+	// Set the table name
+	url.searchParams.set("table", tableName)
+
+	// Add Electric Cloud auth if configured (server-side only, never exposed to browser)
+	if (process.env.ELECTRIC_SOURCE_ID && process.env.ELECTRIC_SECRET) {
+		url.searchParams.set("source_id", process.env.ELECTRIC_SOURCE_ID)
+		url.searchParams.set("secret", process.env.ELECTRIC_SECRET)
+	}
+
+	return url.toString()
+}
+
+export async function proxyElectricRequest(request: Request, tableName: string): Promise<Response> {
+	const url = prepareElectricUrl(request, tableName)
+
+	const response = await fetch(url)
+
+	return new Response(response.body, {
+		status: response.status,
+		headers: {
+			"Content-Type": response.headers.get("Content-Type") || "application/json",
+			"Cache-Control":
+				response.headers.get("Cache-Control") || "no-cache, no-store, must-revalidate",
+			...(response.headers.get("Electric-Handle")
+				? { "Electric-Handle": response.headers.get("Electric-Handle") as string }
+				: {}),
+			...(response.headers.get("Electric-Offset")
+				? { "Electric-Offset": response.headers.get("Electric-Offset") as string }
+				: {}),
+			...(response.headers.get("Electric-Schema")
+				? { "Electric-Schema": response.headers.get("Electric-Schema") as string }
+				: {}),
+			...(response.headers.get("Electric-Cursor")
+				? { "Electric-Cursor": response.headers.get("Electric-Cursor") as string }
+				: {}),
+		},
+	})
+}

package/template/tests/helpers/schema-test-utils.ts

@@ -0,0 +1,106 @@
+import type { ZodObject, ZodRawShape, ZodTypeAny } from "zod"
+
+// Re-export parseDates so tests can import from the test helper
+export { parseDates } from "@/db/utils"
+
+/**
+ * Generate a valid row from a Zod schema by introspecting its shape.
+ * Produces type-appropriate default values for each field.
+ */
+export function generateValidRow<T extends ZodRawShape>(
+	schema: ZodObject<T>,
+): Record<string, unknown> {
+	const shape = schema.shape
+	const row: Record<string, unknown> = {}
+
+	for (const [key, zodType] of Object.entries(shape)) {
+		row[key] = generateValueForType(key, zodType as ZodTypeAny)
+	}
+
+	return row
+}
+
+/**
+ * Generate a valid row with a specific field omitted.
+ * Useful for negative tests that verify required fields.
+ */
+export function generateRowWithout<T extends ZodRawShape>(
+	schema: ZodObject<T>,
+	field: string,
+): Record<string, unknown> {
+	const row = generateValidRow(schema)
+	delete row[field]
+	return row
+}
+
+/**
+ * Resolve the type name from a Zod schema's internal _def.
+ * Handles both Zod v3 (_def.typeName = "ZodString") and
+ * Zod v4 (_def.type = "string") conventions.
+ */
+function resolveTypeName(def: Record<string, unknown>): string | undefined {
+	// Zod v3: _def.typeName is PascalCase like "ZodString"
+	if (typeof def.typeName === "string") return def.typeName
+	// Zod v4: _def.type is lowercase like "string"
+	if (typeof def.type === "string") {
+		const t = def.type as string
+		return `Zod${t.charAt(0).toUpperCase()}${t.slice(1)}`
+	}
+	return undefined
+}
+
+function generateValueForType(key: string, zodType: ZodTypeAny): unknown {
+	// Unwrap optional/nullable/default wrappers to find the inner type
+	const inner = unwrap(zodType)
+	const typeName = inner._def ? resolveTypeName(inner._def as Record<string, unknown>) : undefined
+
+	// UUID fields — id, *Id (camelCase), or *_id (snake_case)
+	if (key === "id" || key.endsWith("Id") || key.endsWith("_id")) {
+		return crypto.randomUUID()
+	}
+
+	// Timestamp fields
+	if (key === "createdAt" || key === "updatedAt" || key.endsWith("_at") || key.endsWith("At")) {
+		return new Date()
+	}
+
+	switch (typeName) {
+		case "ZodString":
+			return `test-${key}`
+		case "ZodNumber":
+		case "ZodFloat":
+			return 0
+		case "ZodInt":
+			return 0
+		case "ZodBoolean":
+			return false
+		case "ZodDate":
+			return new Date()
+		case "ZodEnum":
+			// Return the first enum value
+			return inner._def?.values?.[0] ?? "unknown"
+		case "ZodArray":
+			return []
+		case "ZodUUID":
+			return crypto.randomUUID()
+		default:
+			return `test-${key}`
+	}
+}
+
+function unwrap(zodType: ZodTypeAny): ZodTypeAny {
+	const def = zodType._def as Record<string, unknown> | undefined
+	if (!def) return zodType
+
+	const typeName = resolveTypeName(def)
+	if (typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") {
+		return unwrap(def.innerType as ZodTypeAny)
+	}
+
+	// Zod v4 ZodUnion: unwrap to first option (e.g., z.union([z.date(), z.string()]) → z.date())
+	if (typeName === "ZodUnion" && Array.isArray(def.options)) {
+		return unwrap(def.options[0] as ZodTypeAny)
+	}
+
+	return zodType
+}

package/template/vitest.config.ts

@@ -0,0 +1,7 @@
+import path from "node:path"
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+	resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
+	test: { globals: true, environment: "node" },
+})