@codeyam/codeyam-cli 0.1.0-staging.8421896 → 0.1.0-staging.8778565

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

@@ -0,0 +1,104 @@
+# Supabase + Prisma 7 Setup
+
+This project uses Prisma 7 with PostgreSQL via Supabase.
+
+## Quick start
+
+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
+
+## How it works
+
+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:
+
+```typescript
+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`
+  generator requires a custom output path that breaks Turbopack import resolution.
+- **Do NOT add an `output` field** to the generator. The default output to
+  `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 `turbopack: { root: "." }`** in `next.config.ts`. Without it,
+  Turbopack may infer a parent directory as root and break imports.
+- **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
+# Edit your schema
+vim prisma/schema.prisma
+
+# Push schema changes to the database (also regenerates client)
+npm run db:push
+
+# Seed the database
+npm run db:seed
+
+# Reset the database (drops all tables, re-creates, re-seeds)
+npm run db:reset
+
+# Open Prisma Studio (database browser)
+npx prisma studio
+```
+
+## 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.
+
+## Writing API routes
+
+```typescript
+// app/api/todos/route.ts
+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);
+}
+```
+
+## 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>
+  );
+}

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

@@ -0,0 +1,20 @@
+// Prisma 7 requires a driver adapter for database access.
+// This file uses the pg adapter for Supabase PostgreSQL.
+//
+// Usage in API routes and server components:
+//   import { prisma } from "@/app/lib/prisma";
+//   const items = await prisma.todo.findMany();
+
+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;

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

@@ -0,0 +1,12 @@
+// Supabase client for auth, realtime, and storage.
+// For database queries, use Prisma instead (see prisma.ts).
+//
+// Usage:
+//   import { supabase } from "@/app/lib/supabase";
+
+import { createClient } from '@supabase/supabase-js';
+
+const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
+const supabaseAnonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey);

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

@@ -0,0 +1,10 @@
+export default function Home() {
+  return (
+    <main className="min-h-screen flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold mb-4">Welcome</h1>
+        <p className="text-gray-600">Your app is ready. Start building!</p>
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,9 @@
+# Supabase project credentials
+# Get these from: https://supabase.com/dashboard → Project Settings → API
+NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
+
+# Database connection string (Supabase PostgreSQL)
+# Get this from: Supabase Dashboard → Project Settings → Database → Connection string (URI)
+# Use the "Transaction" connection string for serverless environments (Vercel, etc.)
+DATABASE_URL=postgresql://postgres.YOUR_PROJECT_ID:YOUR_PASSWORD@aws-0-us-east-1.pooler.supabase.com:6543/postgres

package/codeyam-cli/templates/nextjs-prisma-supabase/eslint.config.mjs

@@ -0,0 +1,11 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+]);
+
+export default eslintConfig;

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

@@ -0,0 +1,40 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (contains secrets)
+.env
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

package/codeyam-cli/templates/nextjs-prisma-supabase/next.config.ts

@@ -0,0 +1,11 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  turbopack: {
+    // Required: prevents Turbopack from inferring a parent directory as root
+    // when .codeyam/ exists above the project (which breaks import resolution)
+    root: '.',
+  },
+};
+
+export default nextConfig;

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

@@ -0,0 +1,36 @@
+{
+  "name": "codeyam-project",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "db:push": "npx prisma db push && npx prisma generate",
+    "db:seed": "npx tsx prisma/seed.ts",
+    "db:reset": "npx prisma migrate reset --force"
+  },
+  "dependencies": {
+    "@prisma/adapter-pg": "^7.4.1",
+    "@prisma/client": "^7.4.1",
+    "@supabase/supabase-js": "^2.49.4",
+    "next": "^15.3.3",
+    "pg": "^8.16.0",
+    "prisma": "^7.4.1",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/pg": "^8",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "^15.3.3",
+    "tailwindcss": "^4",
+    "tsx": "^4.19.4",
+    "typescript": "^5"
+  }
+}

package/codeyam-cli/templates/nextjs-prisma-supabase/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/codeyam-cli/templates/nextjs-prisma-supabase/prisma/schema.prisma

@@ -0,0 +1,27 @@
+// Prisma 7 with PostgreSQL via Supabase.
+//
+// IMPORTANT: Use "prisma-client-js" (NOT "prisma-client").
+// The "prisma-client" generator requires a custom output path which
+// breaks Turbopack import resolution and seed script imports.
+// "prisma-client-js" outputs to node_modules/@prisma/client which
+// works everywhere with standard imports.
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+}
+
+// ──────────────────────────────────────────────
+// Replace these placeholder models with your own.
+// After editing, run: npm run db:push
+// ──────────────────────────────────────────────
+
+model Todo {
+  id        Int      @id @default(autoincrement())
+  title     String
+  completed Boolean  @default(false)
+  createdAt DateTime @default(now())
+}

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

@@ -0,0 +1,39 @@
+// Seed script for populating the database with demo data.
+//
+// Run with: npx tsx prisma/seed.ts
+// Or:       npm run db:seed
+//
+// 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 { PrismaPg } from '@prisma/adapter-pg';
+
+const connectionString = process.env.DATABASE_URL!;
+const adapter = new PrismaPg({ connectionString });
+const prisma = new PrismaClient({ adapter });
+
+async function main() {
+  // Clear existing data
+  await prisma.todo.deleteMany();
+
+  // Seed with demo data
+  await prisma.todo.createMany({
+    data: [
+      { title: 'Set up the project', completed: true },
+      { title: 'Build the first feature' },
+      { title: 'Add more scenarios' },
+    ],
+  });
+
+  const count = await prisma.todo.count();
+  console.log(`Seeded ${count} todos`);
+}
+
+main()
+  .then(() => prisma.$disconnect())
+  .catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });

package/codeyam-cli/templates/nextjs-prisma-supabase/prisma.config.ts

@@ -0,0 +1,12 @@
+import 'dotenv/config';
+import { defineConfig } from 'prisma/config';
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',
+  migrations: {
+    path: 'prisma/migrations',
+  },
+  datasource: {
+    url: process.env['DATABASE_URL'],
+  },
+});

package/codeyam-cli/templates/nextjs-prisma-supabase/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/codeyam-cli/templates/prompts/conversation-guidance.txt

@@ -0,0 +1,44 @@
+### What to look for
+
+Read the full transcript for these signals:
+
+**User corrections or redirections**
+- "no", "actually", "that's not right", "you need to also...", "you missed..."
+- User provides information Claude didn't know or couldn't infer from code
+- User reminds Claude of a step, pattern, or relationship
+- A correction about something other than current task requirements is ALWAYS rule-worthy
+
+**Investigation and debugging**
+- Claude tried multiple approaches, read logs, or tested hypotheses
+- Investigation revealed non-obvious behavior or root causes
+- Debugging strategies that worked (or didn't) for specific areas
+
+**Architecture not evident in code**
+- Files that must change together (templates + installation, routes + registration)
+- Complex files, data flows, pipelines, or system interactions that would benefit from an overview
+
+**Commands and workflows**
+- Specific commands or flags needed for this area
+- Order of operations that matters ("must run X before Y")
+
+**Ignore:**
+- Corrections to requirements for the current feature or bug
+- Confusion isolated to the current work session (won't recur)
+
+### Before creating a rule
+
+**Critical check:** Read the actual source files that were modified. If the code already contains comments, guard patterns, or tests that explain the insight, the code is the documentation — skip the rule unless the file is complex and you've made a mistake or the user had to interrupt and correct you.
+
+Show your thinking before proceeding with creating or updating rules.
+
+### How to write rules
+
+**Rules must be forward-looking, not historical.** You are reading a session transcript where bugs were found and fixed, but the rule should describe the *current* codebase, not tell the story of what went wrong, what was fixed, etc. The code has already been updated — past bugs are no longer relevant.
+
+- **DO**: State constraints and requirements ("this script MUST copy directories recursively, not just files")
+- **DO**: Explain *why* something matters ("errors in prompt copying are silently caught, so missing directories won't surface as errors")
+- **DON'T**: Describe what old code did ("the old version only copied files, causing X to be missing")
+- **DON'T**: Narrate the debugging journey ("we discovered that the catch block was swallowing errors")
+- **DON'T**: Note issues or known gaps if they are actively being worked on!
+
+Think of the reader as a developer about to modify these files. They need to know what constraints to preserve and what pitfalls to watch for — not what happened in the past if it is no longer relevant.

package/codeyam-cli/templates/prompts/conversation-prompt.txt

@@ -0,0 +1,28 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+Analyze the conversation transcript for rule-worthy learnings:
+- User corrections, redirections, or information Claude didn't know
+- Investigation results and debugging knowledge
+- Architecture and relationships not obvious from code
+- Commands, workflows, and processes
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/prompts/interruption-prompt.txt

@@ -0,0 +1,31 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+The user interrupted Claude mid-response — a strong signal of confusion or misunderstanding.
+Analyze both Claude's interrupted output and the user's follow-up to determine what went wrong.
+
+Look for:
+- Claude heading in a wrong direction that the user had to correct
+- Misunderstanding of project conventions, architecture, or dependencies
+- Missing context that caused Claude to make incorrect assumptions
+- Patterns that would recur in future sessions without a rule
+
+Access and read files in the repo or in the .claude folder as needed.
+
+Create new rules only when the learnings meet the guidelines in the context file.
+
+IMPORTANT: If you create ANY rule files, write a short summary to `{{NOTIFICATION_FILE}}`. The summary should list each rule change, e.g.:
+```
+The background rule-reflection agent created the following rules:
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+Only write the notification file when rules are created.
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.

package/codeyam-cli/templates/prompts/stale-rules-prompt.txt

@@ -0,0 +1,24 @@
+FIRST: Read `.codeyam/rules/instructions.md` — it contains the required format, rule placement via the rule-path API, and an example rule. You MUST follow this format exactly when creating or editing rules.
+
+THEN: Read the file {{CONTEXT_FILE}} and follow the instructions inside.
+
+For each stale rule:
+1. Review the inline rule content and the diff to determine if the rule needs updating
+2. If it needs updating, edit the rule file in .claude/rules/ — also trim prose and unnecessary headers (most rules should be a few bullets)
+3. Run `codeyam memory touch <rule-path1> <rule-path2> ...` with the SPECIFIC rule paths you reviewed to mark them as audited in .claude/codeyam-rule-state.json
+   Example: `codeyam memory touch tooling/cli-build.md packages/ai/execution-flow-prioritization.md`
+
+Write a summary to `{{NOTIFICATION_FILE}}` listing each action taken, even if you only ran `codeyam memory touch` without content changes. Example:
+```
+The background rule-reflection agent updated the following rules:
+- Reviewed `.claude/rules/example.md` — no content changes, ran `codeyam memory touch`
+- Created `.claude/rules/tooling/new-pattern.md` — documents X pattern
+```
+
+The project root is {{PROJECT_DIR}}
+
+CRITICAL: All rule files MUST be written to {{PROJECT_DIR}}/.claude/rules/ (the project directory), NOT ~/.claude/rules/ (the user home directory). Always use the full absolute path when writing rule files.
+
+CRITICAL: Before writing any rule file, you MUST run the rule-path command to determine the correct subdirectory:
+  codeyam memory rule-path path/one path/two
+Pass all paths from your frontmatter. The command returns the correct .claude/rules/ subdirectory as JSON. Do NOT guess the placement from the first path — rules with paths spanning multiple directories belong at their common ancestor.