@codeyam/codeyam-cli 0.1.8 → 0.1.9

package/codeyam-cli/templates/nextjs-prisma-sqlite/DATABASE.md

@@ -0,0 +1,126 @@
+# Database
+
+This project uses **Prisma 7 with SQLite** for local development. No external services needed.
+
+All application code imports from `@/app/lib/prisma` — this is the only file that changes when you upgrade to a hosted database.
+
+## Quick Reference
+
+```bash
+# Edit your schema
+vim prisma/schema.prisma
+
+# Push schema changes (also regenerates Prisma client)
+npm run db:push
+
+# Seed demo data
+npm run db:seed
+
+# Reset database (delete + recreate + seed)
+npm run db:reset
+
+# Browse data visually
+npx prisma studio
+```
+
+## Adding Columns to Existing Tables
+
+When adding a new **required** column to a table that already has data, `db push` will fail because existing rows have no value for the new column. To avoid this:
+
+- **Add a `@default(...)` value** so Prisma can fill existing rows automatically:
+  ```prisma
+  model Rating {
+    userId String @default("anonymous")  // existing rows get "anonymous"
+  }
+  ```
+- Once all rows have real values, you can remove the default if desired.
+- **Never use `--force-reset`** — it drops ALL tables and deletes all data.
+- Optional columns (`String?`) don't need a default — existing rows get `null`.
+
+## Using the Database
+
+```typescript
+import { prisma } from '@/app/lib/prisma';
+
+// In API routes or server components:
+const items = await prisma.todo.findMany();
+const item = await prisma.todo.create({ data: { title: 'New item' } });
+```
+
+## Important: Do NOT Change These Settings
+
+- **Generator must be `prisma-client-js`** (not `prisma-client`). The `prisma-client` generator requires a custom output path that breaks Turbopack.
+- **Do NOT add an `output` field** to the generator.
+- **Do NOT add `url` to the datasource block** in `schema.prisma`. Prisma 7 moved the URL to `prisma.config.ts`.
+- **Keep `serverExternalPackages: ["better-sqlite3"]`** in `next.config.ts`.
+- **Keep `turbopack: { root: "." }`** in `next.config.ts`.
+- **Always run `npx prisma generate`** after `npx prisma db push` (or use `npm run db:push` which does both).
+- **Database file is at project root** (`./dev.db`), not in `prisma/`.
+
+## Upgrading to a Hosted Database
+
+When you're ready for production, you'll want a hosted database. SQLite is great for prototyping, but doesn't support concurrent connections or run in serverless environments (Vercel, etc.).
+
+### Option 1: Supabase (PostgreSQL)
+
+Free tier available. Gives you PostgreSQL + auth + realtime + storage.
+
+1. Create a project at https://supabase.com/dashboard
+2. Get your credentials from Project Settings > Database > Connection string (URI)
+3. Replace packages:
+   ```bash
+   npm uninstall better-sqlite3 @prisma/adapter-better-sqlite3 @types/better-sqlite3
+   npm install @prisma/adapter-pg pg @supabase/supabase-js
+   npm install -D @types/pg
+   ```
+4. Update `prisma/schema.prisma`:
+   ```prisma
+   datasource db {
+     provider = "postgresql"
+   }
+   ```
+5. Update `app/lib/prisma.ts`:
+
+   ```typescript
+   import { PrismaClient } from '@prisma/client';
+   import { PrismaPg } from '@prisma/adapter-pg';
+
+   const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+   const connectionString = process.env.DATABASE_URL!;
+   const adapter = new PrismaPg({ connectionString });
+   export const prisma =
+     globalForPrisma.prisma ?? new PrismaClient({ adapter });
+   if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+   export default prisma;
+   ```
+
+6. Create `.env`:
+   ```
+   DATABASE_URL=postgresql://postgres.YOUR_PROJECT_ID:YOUR_PASSWORD@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+   ```
+7. Remove `serverExternalPackages` from `next.config.ts`
+8. Run `npm run db:push` to create tables in Supabase
+9. Update `prisma/seed.ts` to use the new adapter (same pattern as `prisma.ts`)
+
+### Option 2: Other PostgreSQL Hosts (Neon, Railway, etc.)
+
+Same steps as Supabase above (steps 3-9), just use your provider's connection string.
+
+### Option 3: PlanetScale / MySQL
+
+1. Replace packages:
+   ```bash
+   npm uninstall better-sqlite3 @prisma/adapter-better-sqlite3 @types/better-sqlite3
+   npm install @prisma/adapter-planetscale @planetscale/database
+   ```
+2. Update `schema.prisma` datasource to `provider = "mysql"`
+3. Update `app/lib/prisma.ts` to use `PrismaPlanetScale` adapter
+4. Follow PlanetScale setup docs for connection string
+
+### What Stays the Same
+
+Your application code doesn't change at all. Every file that uses the database already imports from `@/app/lib/prisma`, which is the only file that gets updated. Your Prisma schema models, API routes, and server components all work identically regardless of which database backs them.
+
+## Writing Seed Scripts
+
+Seed scripts run outside of Next.js, so they must create their own PrismaClient with the adapter (they cannot import from `@/app/lib/prisma`). See `prisma/seed.ts` for the correct pattern.

package/codeyam-cli/templates/nextjs-prisma-sqlite/FEATURE_PATTERNS.md

@@ -0,0 +1,37 @@
+# Feature Patterns
+
+When the feature you're building involves any of the patterns below, **read the linked doc before writing code**. These patterns are designed for the local SQLite dev environment and upgrade cleanly to production services later.
+
+## Authentication (login, sign-up, user sessions)
+
+**Read:** `AUTH_PATTERNS.md`
+
+Use the cookie + DB auth abstraction in `app/lib/auth.ts`. All consumer code imports from this single file. DO NOT use NextAuth, Clerk, better-auth, Supabase Auth, or any external auth provider during prototyping — they require infrastructure unavailable locally.
+
+**For scenarios:** Include User and Session seed rows. Add `"session": {"cookieValue": "<token>"}` at the scenario top level to auto-log the user in. Omit `session` for a logged-out scenario.
+
+**Upgrade path:** See `AUTH_UPGRADE.md` — only `app/lib/auth.ts` internals change; consumer code stays the same.
+
+## External Services (payments, email, maps, weather APIs, etc.)
+
+If the user has dev/test credentials (e.g., Stripe test keys):
+
+- Store them in `.codeyam/config.json` under `environmentVariables`
+- Restart the dev server — credentials are injected into `process.env`
+
+If no credentials are available:
+
+- Build with real API calls in the code
+- Mock responses per scenario using `externalApis` in scenario registration (Step 8)
+
+## File Storage / Uploads
+
+For local prototyping, store files in the `public/uploads/` directory and serve them as static assets. Use `fs.writeFile` in API routes. For production, swap to S3/Cloudflare R2/Supabase Storage.
+
+## Email / Notifications
+
+For prototyping, log emails to the console or write them to a `/api/dev/sent-emails` endpoint that stores in the database. For production, swap to Resend/SendGrid/Postmark.
+
+---
+
+_This list will grow as new patterns are added. Each pattern follows the same principle: build with a simple local implementation, upgrade to a production service later by swapping one file._

package/codeyam-cli/templates/nextjs-prisma-sqlite/README.md

@@ -0,0 +1,53 @@
+# Project Name
+
+Brief description of what this app does.
+
+## Setup
+
+Run the setup script to install dependencies, initialize the database, and seed it with demo data:
+
+```bash
+npm run setup
+```
+
+## Development
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Using CodeYam Editor
+
+This project was built with [CodeYam](https://codeyam.com). To launch the editor:
+
+```bash
+codeyam editor
+```
+
+The editor provides a live preview alongside a Claude Code terminal for iterating on the app.
+
+## Database
+
+This project uses SQLite via Prisma. Common commands:
+
+```bash
+npm run db:push    # Apply schema changes and generate Prisma client
+npm run db:seed    # Seed the database with demo data
+npm run db:reset   # Reset database: drop, recreate, and re-seed
+```
+
+## Scripts
+
+| Script             | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `npm run setup`    | One-line project setup (install + db + seed) |
+| `npm run dev`      | Start the development server                 |
+| `npm run build`    | Build for production                         |
+| `npm run test`     | Run tests                                    |
+| `npm run db:push`  | Apply Prisma schema changes                  |
+| `npm run db:seed`  | Seed the database                            |
+| `npm run db:reset` | Reset and re-seed the database               |

package/codeyam-cli/templates/nextjs-prisma-sqlite/app/codeyam-isolate/layout.tsx

@@ -0,0 +1,12 @@
+import { notFound } from 'next/navigation';
+
+export default function CodeYamIsolateLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  if (process.env.NODE_ENV === 'production') {
+    notFound();
+  }
+  return <>{children}</>;
+}

package/codeyam-cli/templates/nextjs-prisma-sqlite/app/lib/prisma.ts

@@ -1,16 +1,21 @@
-// Prisma 7 requires a driver adapter for database access.
-// This file uses better-sqlite3 for SQLite.
+// Database connection singleton.
+// This is the ONLY file that changes when upgrading to a hosted database.
+// All application code imports from here — API routes, server components, etc.
 //
-// Usage in API routes and server components:
+// Usage:
 //   import { prisma } from "@/app/lib/prisma";
 //   const items = await prisma.todo.findMany();
+//
+// To upgrade to a hosted database (e.g., Supabase PostgreSQL), see DATABASE.md.
 
 import { PrismaClient } from '@prisma/client';
 import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
 
 const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
 
-const adapter = new PrismaBetterSqlite3({ url: 'file:./dev.db' });
+const adapter = new PrismaBetterSqlite3({
+  url: process.env.DATABASE_URL || 'file:./dev.db',
+});
 
 export const prisma = globalForPrisma.prisma ?? new PrismaClient({ adapter });
 

package/codeyam-cli/templates/nextjs-prisma-sqlite/env

@@ -0,0 +1,4 @@
+# Local SQLite database (no external services needed)
+# This is used by Prisma CLI commands (db push, migrate, etc.)
+# The app code in app/lib/prisma.ts also uses this path.
+DATABASE_URL=file:./dev.db

package/codeyam-cli/templates/nextjs-prisma-sqlite/gitignore

@@ -41,3 +41,24 @@ next-env.d.ts
 # database
 dev.db
 dev.db-journal
+
+# CodeYam - local only (not shared)
+.codeyam/db.sqlite3
+.codeyam/db.sqlite3-wal
+.codeyam/db.sqlite3-shm
+.codeyam/secrets.json
+.codeyam/server.json
+.codeyam/server-state.json
+.codeyam/queue.json
+.codeyam/active-scenario.json
+.codeyam/editor-step.json
+.codeyam/editor-user-prompt.txt
+.codeyam/editor-mode-context.md
+.codeyam/dev-mode-context.md
+.codeyam/logs/
+.codeyam/llm-calls/
+.codeyam/captures/
+.codeyam/results/
+.codeyam/tmp/
+.codeyam/rules/
+.codeyam/bin/

package/codeyam-cli/templates/nextjs-prisma-sqlite/package.json

@@ -3,10 +3,13 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
+    "setup": "npm install && npm run db:push && npm run db:seed",
     "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
     "lint": "eslint",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "db:push": "npx prisma db push && npx prisma generate",
     "db:seed": "npx tsx prisma/seed.ts",
     "db:reset": "rm -f dev.db && npm run db:push && npx tsx prisma/seed.ts"
@@ -30,6 +33,7 @@
     "eslint-config-next": "^15.3.3",
     "tailwindcss": "^4",
     "tsx": "^4.19.4",
-    "typescript": "^5"
+    "typescript": "^5",
+    "vitest": "^3"
   }
 }

package/codeyam-cli/templates/nextjs-prisma-sqlite/prisma/seed.ts

@@ -6,10 +6,13 @@
 // IMPORTANT: This file must use the same adapter pattern as app/lib/prisma.ts.
 // Do NOT use `new PrismaClient()` without the adapter — Prisma 7 requires it.
 
+import 'dotenv/config';
 import { PrismaClient } from '@prisma/client';
 import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
 
-const adapter = new PrismaBetterSqlite3({ url: 'file:./dev.db' });
+const adapter = new PrismaBetterSqlite3({
+  url: process.env.DATABASE_URL || 'file:./dev.db',
+});
 const prisma = new PrismaClient({ adapter });
 
 async function main() {

package/codeyam-cli/templates/nextjs-prisma-sqlite/seed-adapter.ts

@@ -0,0 +1,92 @@
+/**
+ * CodeYam Seed Adapter for Prisma + SQLite.
+ *
+ * Reads a JSON seed data file (path passed as CLI arg), wipes all tables,
+ * then inserts the seed data using Prisma.
+ *
+ * Usage: npx tsx .codeyam/seed-adapter.ts <path-to-seed-data.json>
+ *
+ * The JSON file has the format:
+ * {
+ *   "type": "application",
+ *   "seed": {
+ *     "tableName": [{ "column": "value", ... }, ...]
+ *   },
+ *   "externalApis": { ... }  // optional, not used by this adapter
+ * }
+ */
+
+import 'dotenv/config';
+import { PrismaClient } from '@prisma/client';
+import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
+import * as fs from 'fs';
+
+const adapter = new PrismaBetterSqlite3({
+  url: process.env.DATABASE_URL || 'file:./dev.db',
+});
+const prisma = new PrismaClient({ adapter });
+
+async function main() {
+  const seedDataPath = process.argv[2];
+  if (!seedDataPath) {
+    console.error('Usage: npx tsx .codeyam/seed-adapter.ts <seed-data.json>');
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(seedDataPath, 'utf-8');
+  const data = JSON.parse(raw);
+  const seed = data.seed || data;
+
+  console.log(`Seeding tables: ${Object.keys(seed).join(', ')}`);
+
+  // Wipe all tables in reverse order (to respect foreign keys)
+  const tableNames = Object.keys(seed);
+  for (const table of [...tableNames].reverse()) {
+    try {
+      await (prisma as any)[table].deleteMany();
+      console.log(`  Cleared ${table}`);
+    } catch (err) {
+      console.warn(
+        `  Could not clear ${table}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+  }
+
+  // Reset auto-increment counters so IDs start from 1 after each re-seed.
+  // Without this, SQLite IDs keep climbing (1, 2, ... then 9, 10, ...)
+  // across scenario switches, causing hardcoded URLs like /drinks/1 to 404.
+  for (const table of tableNames) {
+    try {
+      // Prisma uses PascalCase model names; sqlite_sequence stores the actual table name.
+      // Try both the seed key (which matches the Prisma model) and common casings.
+      await prisma.$executeRawUnsafe(
+        `DELETE FROM sqlite_sequence WHERE name = '${table}' OR name = '${table.charAt(0).toUpperCase() + table.slice(1)}'`,
+      );
+    } catch {
+      // sqlite_sequence may not exist if no autoincrement columns — safe to ignore
+    }
+  }
+
+  // Insert seed data
+  for (const [table, rows] of Object.entries(seed)) {
+    if (!Array.isArray(rows) || rows.length === 0) continue;
+    try {
+      await (prisma as any)[table].createMany({ data: rows });
+      console.log(`  Seeded ${rows.length} rows into ${table}`);
+    } catch (err) {
+      console.error(
+        `  Failed to seed ${table}: ${err instanceof Error ? err.message : err}`,
+      );
+      process.exit(1);
+    }
+  }
+
+  console.log('Seed complete');
+}
+
+main()
+  .then(() => prisma.$disconnect())
+  .catch((e) => {
+    console.error('Seed adapter error:', e);
+    process.exit(1);
+  });

package/codeyam-cli/templates/nextjs-prisma-sqlite/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, '.'),
+    },
+  },
+});

package/codeyam-cli/templates/nextjs-prisma-supabase/README.md

@@ -0,0 +1,52 @@
+# Project Name
+
+Brief description of what this app does.
+
+## Setup
+
+Run the setup script to install dependencies, initialize the database, and seed it with demo data:
+
+```bash
+npm run setup
+```
+
+## Development
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Using CodeYam Editor
+
+This project was built with [CodeYam](https://codeyam.com). To launch the editor:
+
+```bash
+codeyam editor
+```
+
+The editor provides a live preview alongside a Claude Code terminal for iterating on the app.
+
+## Database
+
+This project uses Supabase (PostgreSQL) via Prisma. Common commands:
+
+```bash
+npm run db:push    # Apply schema changes and generate Prisma client
+npm run db:seed    # Seed the database with demo data
+npm run db:reset   # Reset database (runs prisma migrate reset)
+```
+
+## Scripts
+
+| Script             | Description                                  |
+| ------------------ | -------------------------------------------- |
+| `npm run setup`    | One-line project setup (install + db + seed) |
+| `npm run dev`      | Start the development server                 |
+| `npm run build`    | Build for production                         |
+| `npm run db:push`  | Apply Prisma schema changes                  |
+| `npm run db:seed`  | Seed the database                            |
+| `npm run db:reset` | Reset the database                           |

package/codeyam-cli/templates/{nextjs-prisma-sqlite/PRISMA_SETUP.md → nextjs-prisma-supabase/SUPABASE_SETUP.md}

@@ -1,19 +1,17 @@
-# Prisma 7 + SQLite Setup
+# Supabase + Prisma 7 Setup
 
-This project uses Prisma 7 with SQLite via the `better-sqlite3` driver adapter.
+This project uses Prisma 7 with PostgreSQL via Supabase.
 
-## How it works
+## Quick start
 
-Prisma 7 requires a **driver adapter** — you cannot use `new PrismaClient()` alone.
-Every file that creates a PrismaClient must use this pattern:
+1. Create a Supabase project at https://supabase.com/dashboard
+2. Copy `.env` and fill in your credentials (see comments in the file)
+3. Run `npm run db:push` to create tables
+4. Run `npm run db:seed` to populate demo data
 
-```typescript
-import { PrismaClient } from '@prisma/client';
-import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
+## How it works
 
-const adapter = new PrismaBetterSqlite3({ url: 'file:./dev.db' });
-const prisma = new PrismaClient({ adapter });
-```
+Prisma 7 requires a **driver adapter**. This project uses `@prisma/adapter-pg` with the `pg` package to connect to Supabase's PostgreSQL.
 
 The singleton in `app/lib/prisma.ts` is already configured. Import it in your code:
 
@@ -21,6 +19,12 @@ The singleton in `app/lib/prisma.ts` is already configured. Import it in your co
 import { prisma } from '@/app/lib/prisma';
 ```
 
+For Supabase-specific features (auth, realtime, storage), use the Supabase client:
+
+```typescript
+import { supabase } from '@/app/lib/supabase';
+```
+
 ## Important: do NOT change these settings
 
 - **Generator must be `prisma-client-js`** (not `prisma-client`). The `prisma-client`
@@ -29,14 +33,19 @@ import { prisma } from '@/app/lib/prisma';
   `node_modules/@prisma/client` works with standard imports everywhere.
 - **Do NOT add `url` to the datasource block** in `schema.prisma`. Prisma 7
   moved the URL to `prisma.config.ts`. Adding it to the schema causes a validation error.
-- **Keep `serverExternalPackages: ["better-sqlite3"]`** in `next.config.ts`.
-  Without it, Next.js tries to bundle the native module and fails.
 - **Keep `turbopack: { root: "." }`** in `next.config.ts`. Without it,
   Turbopack may infer a parent directory as root and break imports.
-- **Database file is at project root** (`./dev.db`), not in `prisma/`.
 - **Always run `npx prisma generate`** after `npx prisma db push` (or use
   `npm run db:push` which does both). Without this, the client module is missing.
 
+## Getting your Supabase credentials
+
+1. Go to https://supabase.com/dashboard and select your project
+2. **SUPABASE_URL** and **SUPABASE_ANON_KEY**: Project Settings → API
+3. **DATABASE_URL**: Project Settings → Database → Connection string (URI)
+   - For serverless (Vercel, etc.): use the "Transaction" pooler connection string (port 6543)
+   - For long-running servers: use the "Session" pooler connection string (port 5432)
+
 ## Common tasks
 
 ```bash
@@ -47,10 +56,9 @@ vim prisma/schema.prisma
 npm run db:push
 
 # Seed the database
-npx tsx prisma/seed.ts
-# or: npm run db:seed
+npm run db:seed
 
-# Reset the database (delete + recreate + seed)
+# Reset the database (drops all tables, re-creates, re-seeds)
 npm run db:reset
 
 # Open Prisma Studio (database browser)
@@ -82,3 +90,15 @@ export async function POST(request: Request) {
   return Response.json(todo);
 }
 ```
+
+## Deployment
+
+This template is ready to deploy to Vercel:
+
+1. Push your code to GitHub
+2. Import the repo in Vercel
+3. Add the same environment variables from `.env` to Vercel's project settings
+4. Deploy
+
+The DATABASE_URL should use Supabase's **Transaction** pooler connection string
+(port 6543) for serverless environments like Vercel.

package/codeyam-cli/templates/nextjs-prisma-supabase/app/api/todos/route.ts

@@ -0,0 +1,17 @@
+// Example API route using Prisma.
+// Import prisma from the singleton — do NOT create a new PrismaClient here.
+
+import { prisma } from '@/app/lib/prisma';
+
+export async function GET() {
+  const todos = await prisma.todo.findMany({
+    orderBy: { createdAt: 'desc' },
+  });
+  return Response.json(todos);
+}
+
+export async function POST(request: Request) {
+  const { title } = await request.json();
+  const todo = await prisma.todo.create({ data: { title } });
+  return Response.json(todo);
+}

package/codeyam-cli/templates/nextjs-prisma-supabase/app/globals.css

@@ -0,0 +1,26 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}

package/codeyam-cli/templates/nextjs-prisma-supabase/app/layout.tsx

@@ -0,0 +1,34 @@
+import type { Metadata } from 'next';
+import { Geist, Geist_Mono } from 'next/font/google';
+import './globals.css';
+
+const geistSans = Geist({
+  variable: '--font-geist-sans',
+  subsets: ['latin'],
+});
+
+const geistMono = Geist_Mono({
+  variable: '--font-geist-mono',
+  subsets: ['latin'],
+});
+
+export const metadata: Metadata = {
+  title: 'CodeYam App',
+  description: 'Built with CodeYam Editor',
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body
+        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}