@codeyam/codeyam-cli 0.1.0-staging.da5baf5 → 0.1.0-staging.dbc742d

package/codeyam-cli/templates/isolation-route/next-app.tsx.template

@@ -0,0 +1,80 @@
+/**
+ * CodeYam Isolation Route — Next.js App Router
+ *
+ * Place this file at: app/__codeyam__/[component]/[scenario]/page.tsx
+ *
+ * This route dynamically imports a component and renders it with mock data
+ * from the specified scenario, enabling isolated component preview.
+ *
+ * Usage: http://localhost:3000/__codeyam__/TaskCard/Default
+ */
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useParams } from 'next/navigation';
+
+interface ScenarioData {
+  mockData: Record<string, unknown>;
+}
+
+export default function CodeYamIsolationPage() {
+  const params = useParams();
+  const componentName = params.component as string;
+  const scenarioSlug = params.scenario as string;
+
+  const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
+  const [mockData, setMockData] = useState<Record<string, unknown> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function loadComponent() {
+      try {
+        // Fetch scenario data from CodeYam API
+        const res = await fetch(
+          `http://localhost:${process.env.NEXT_PUBLIC_CODEYAM_PORT || '3111'}/api/editor-scenario-data?component=${componentName}&scenario=${scenarioSlug}`
+        );
+        if (res.ok) {
+          const data: ScenarioData = await res.json();
+          setMockData(data.mockData);
+        }
+
+        // Try to dynamically import the component
+        // Claude should update this mapping when adding new components
+        const componentModules: Record<string, () => Promise<any>> = {
+          // Example: 'TaskCard': () => import('@/components/TaskCard'),
+        };
+
+        const loader = componentModules[componentName];
+        if (loader) {
+          const mod = await loader();
+          setComponent(() => mod.default || mod[componentName]);
+        } else {
+          setError(`Component "${componentName}" not registered in isolation route`);
+        }
+      } catch (err) {
+        setError(`Failed to load component: ${err}`);
+      }
+    }
+
+    void loadComponent();
+  }, [componentName, scenarioSlug]);
+
+  if (error) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#e74c3c' }}>
+        <h2>CodeYam Isolation Error</h2>
+        <p>{error}</p>
+      </div>
+    );
+  }
+
+  if (!Component || !mockData) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#666' }}>
+        Loading {componentName} / {scenarioSlug}...
+      </div>
+    );
+  }
+
+  return <Component {...mockData} />;
+}

package/codeyam-cli/templates/isolation-route/next-pages.tsx.template

@@ -0,0 +1,79 @@
+/**
+ * CodeYam Isolation Route — Next.js Pages Router
+ *
+ * Place this file at: pages/__codeyam__/[component]/[scenario].tsx
+ *
+ * This route dynamically imports a component and renders it with mock data
+ * from the specified scenario, enabling isolated component preview.
+ *
+ * Usage: http://localhost:3000/__codeyam__/TaskCard/Default
+ */
+import { useRouter } from 'next/router';
+import { useEffect, useState } from 'react';
+
+interface ScenarioData {
+  mockData: Record<string, unknown>;
+}
+
+export default function CodeYamIsolationPage() {
+  const router = useRouter();
+  const { component: componentName, scenario: scenarioSlug } = router.query;
+
+  const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
+  const [mockData, setMockData] = useState<Record<string, unknown> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!componentName || !scenarioSlug) return;
+
+    async function loadComponent() {
+      try {
+        // Fetch scenario data from CodeYam API
+        const res = await fetch(
+          `http://localhost:${process.env.NEXT_PUBLIC_CODEYAM_PORT || '3111'}/api/editor-scenario-data?component=${componentName}&scenario=${scenarioSlug}`
+        );
+        if (res.ok) {
+          const data: ScenarioData = await res.json();
+          setMockData(data.mockData);
+        }
+
+        // Try to dynamically import the component
+        // Claude should update this mapping when adding new components
+        const componentModules: Record<string, () => Promise<any>> = {
+          // Example: 'TaskCard': () => import('../components/TaskCard'),
+        };
+
+        const loader = componentModules[componentName as string];
+        if (loader) {
+          const mod = await loader();
+          setComponent(() => mod.default || mod[componentName as string]);
+        } else {
+          setError(`Component "${componentName}" not registered in isolation route`);
+        }
+      } catch (err) {
+        setError(`Failed to load component: ${err}`);
+      }
+    }
+
+    void loadComponent();
+  }, [componentName, scenarioSlug]);
+
+  if (error) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#e74c3c' }}>
+        <h2>CodeYam Isolation Error</h2>
+        <p>{error}</p>
+      </div>
+    );
+  }
+
+  if (!Component || !mockData) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#666' }}>
+        Loading {componentName} / {scenarioSlug}...
+      </div>
+    );
+  }
+
+  return <Component {...mockData} />;
+}

package/codeyam-cli/templates/isolation-route/vite-react.tsx.template

@@ -0,0 +1,78 @@
+/**
+ * CodeYam Isolation Route — Vite + React
+ *
+ * Add this route to your React Router config.
+ * For example, in your router setup:
+ *   { path: '/__codeyam__/:component/:scenario', element: <CodeYamIsolation /> }
+ *
+ * Usage: http://localhost:5173/__codeyam__/TaskCard/Default
+ */
+import { useParams } from 'react-router-dom';
+import { useEffect, useState } from 'react';
+
+interface ScenarioData {
+  mockData: Record<string, unknown>;
+}
+
+export default function CodeYamIsolation() {
+  const { component: componentName, scenario: scenarioSlug } = useParams();
+
+  const [Component, setComponent] = useState<React.ComponentType<any> | null>(null);
+  const [mockData, setMockData] = useState<Record<string, unknown> | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!componentName || !scenarioSlug) return;
+
+    async function loadComponent() {
+      try {
+        // Fetch scenario data from CodeYam API
+        const codeyamPort = import.meta.env.VITE_CODEYAM_PORT || '3111';
+        const res = await fetch(
+          `http://localhost:${codeyamPort}/api/editor-scenario-data?component=${componentName}&scenario=${scenarioSlug}`
+        );
+        if (res.ok) {
+          const data: ScenarioData = await res.json();
+          setMockData(data.mockData);
+        }
+
+        // Try to dynamically import the component
+        // Claude should update this mapping when adding new components
+        const componentModules: Record<string, () => Promise<any>> = {
+          // Example: 'TaskCard': () => import('./components/TaskCard'),
+        };
+
+        const loader = componentModules[componentName];
+        if (loader) {
+          const mod = await loader();
+          setComponent(() => mod.default || mod[componentName]);
+        } else {
+          setError(`Component "${componentName}" not registered in isolation route`);
+        }
+      } catch (err) {
+        setError(`Failed to load component: ${err}`);
+      }
+    }
+
+    void loadComponent();
+  }, [componentName, scenarioSlug]);
+
+  if (error) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#e74c3c' }}>
+        <h2>CodeYam Isolation Error</h2>
+        <p>{error}</p>
+      </div>
+    );
+  }
+
+  if (!Component || !mockData) {
+    return (
+      <div style={{ padding: 24, fontFamily: 'monospace', color: '#666' }}>
+        Loading {componentName} / {scenarioSlug}...
+      </div>
+    );
+  }
+
+  return <Component {...mockData} />;
+}

package/codeyam-cli/templates/msw/browser-setup.ts.template

@@ -0,0 +1,47 @@
+/**
+ * MSW Browser Setup — CodeYam Editor Mode
+ *
+ * This file sets up Mock Service Worker in the browser.
+ * Import this in your app's entry point (e.g., main.tsx or layout.tsx).
+ *
+ * Usage:
+ *   import { startMSW } from './__codeyam-msw__/browser';
+ *   await startMSW();
+ */
+import { setupWorker } from 'msw/browser';
+import { getHandlers } from './index';
+
+let started = false;
+
+export async function startMSW() {
+  if (started) return;
+  if (typeof window === 'undefined') return;
+
+  try {
+    // Read active scenario from CodeYam
+    let scenarioSlug = 'Default';
+    try {
+      const res = await fetch('/.codeyam/active-scenario.json');
+      if (res.ok) {
+        const data = await res.json();
+        scenarioSlug = data.scenarioSlug || 'Default';
+      }
+    } catch {
+      // Use default
+    }
+
+    const handlers = getHandlers(scenarioSlug);
+    if (handlers.length === 0) return;
+
+    const worker = setupWorker(...handlers);
+    await worker.start({
+      onUnhandledRequest: 'bypass',
+      quiet: true,
+    });
+
+    started = true;
+    console.log(`[CodeYam MSW] Browser mocking started (scenario: ${scenarioSlug})`);
+  } catch (error) {
+    console.warn('[CodeYam MSW] Failed to start browser mocking:', error);
+  }
+}

package/codeyam-cli/templates/msw/handler-router.ts.template

@@ -0,0 +1,47 @@
+/**
+ * MSW Handler Router — CodeYam Editor Mode
+ *
+ * Central router that collects handlers from all scenario handler files.
+ * Handler files live in `.codeyam/msw-handlers/{ScenarioSlug}.ts`.
+ *
+ * This file should be placed at `src/__codeyam-msw__/index.ts` in the user's project.
+ */
+import type { RequestHandler } from 'msw';
+
+// Map of scenario slugs to their handler modules.
+// Claude adds imports here as scenarios are created.
+// Example:
+//   import * as Dashboard_Default from '../../.codeyam/msw-handlers/Dashboard_Default';
+//   import * as TaskCard_Empty from '../../.codeyam/msw-handlers/TaskCard_Empty';
+
+const handlerModules: Record<string, { handlers: () => RequestHandler[] }> = {
+  // Claude registers handler modules here:
+  // 'Dashboard_Default': Dashboard_Default,
+  // 'TaskCard_Empty': TaskCard_Empty,
+};
+
+/**
+ * Get MSW handlers for a specific scenario.
+ * Falls back to 'Default' if the requested scenario doesn't have handlers.
+ */
+export function getHandlers(scenarioSlug: string): RequestHandler[] {
+  const module = handlerModules[scenarioSlug];
+  if (module) {
+    return module.handlers();
+  }
+
+  // Try to find a default handler
+  const defaultModule = handlerModules['Default'];
+  if (defaultModule) {
+    return defaultModule.handlers();
+  }
+
+  return [];
+}
+
+/**
+ * Get all available scenario slugs that have MSW handlers.
+ */
+export function getAvailableScenarios(): string[] {
+  return Object.keys(handlerModules);
+}

package/codeyam-cli/templates/msw/server-setup.ts.template

@@ -0,0 +1,52 @@
+/**
+ * MSW Server Setup — CodeYam Editor Mode
+ *
+ * This file sets up Mock Service Worker for server-side interception (Node.js).
+ * For Next.js: import in `instrumentation.ts`.
+ * For Vite SSR: import in the server entry.
+ *
+ * Usage:
+ *   import { startMSWServer } from './__codeyam-msw__/server';
+ *   startMSWServer();
+ */
+import { setupServer } from 'msw/node';
+import { getHandlers } from './index';
+import * as fs from 'fs';
+import * as path from 'path';
+
+let started = false;
+
+export function startMSWServer() {
+  if (started) return;
+
+  try {
+    // Read active scenario from .codeyam/active-scenario.json
+    let scenarioSlug = 'Default';
+    try {
+      const activeScenarioPath = path.join(
+        process.cwd(),
+        '.codeyam',
+        'active-scenario.json',
+      );
+      if (fs.existsSync(activeScenarioPath)) {
+        const data = JSON.parse(fs.readFileSync(activeScenarioPath, 'utf8'));
+        scenarioSlug = data.scenarioSlug || 'Default';
+      }
+    } catch {
+      // Use default
+    }
+
+    const handlers = getHandlers(scenarioSlug);
+    if (handlers.length === 0) return;
+
+    const server = setupServer(...handlers);
+    server.listen({
+      onUnhandledRequest: 'bypass',
+    });
+
+    started = true;
+    console.log(`[CodeYam MSW] Server mocking started (scenario: ${scenarioSlug})`);
+  } catch (error) {
+    console.warn('[CodeYam MSW] Failed to start server mocking:', error);
+  }
+}

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

@@ -0,0 +1,308 @@
+# Auth Patterns for Dev Prototyping
+
+This project uses a simple cookie + database auth pattern designed for local development.
+It is **intentionally simple** — built for easy upgrade to a real provider later.
+
+## DO NOT use external auth providers during prototyping
+
+**Do NOT use NextAuth, Auth.js, Clerk, better-auth, Supabase Auth, or any external auth provider.**
+
+These providers require external infrastructure (OAuth endpoints, JWT signing keys, callback URLs)
+that is unavailable in the local SQLite development environment. They will fail silently or produce
+confusing errors. Use the pattern below instead — it works immediately and upgrades cleanly later.
+
+See `AUTH_UPGRADE.md` for how to swap in a real provider when going to production.
+
+## Interfaces
+
+All consumer code imports from `@/app/lib/auth`. The interface is:
+
+```typescript
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+export async function getSession(): Promise<Session | null>;
+export async function requireAuth(): Promise<Session>; // redirects to /login if no session
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null>;
+export async function signOut(): Promise<void>;
+```
+
+## Prisma Schema Additions
+
+Add these models to `prisma/schema.prisma`:
+
+```prisma
+model User {
+  id        String    @id @default(cuid())
+  name      String
+  email     String    @unique
+  password  String
+  image     String?
+  sessions  Session[]
+  createdAt DateTime  @default(now())
+}
+
+model Session {
+  id        String   @id @default(cuid())
+  token     String   @unique
+  userId    String
+  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+  createdAt DateTime @default(now())
+}
+```
+
+After editing the schema, run: `npm run db:push`
+
+## Dev Implementation: `app/lib/auth.ts`
+
+```typescript
+import { cookies } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { prisma } from '@/app/lib/prisma';
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  image?: string | null;
+}
+
+export interface Session {
+  user: AuthUser;
+}
+
+const COOKIE_NAME = 'session-token';
+
+export async function getSession(): Promise<Session | null> {
+  const cookieStore = await cookies();
+  const token = cookieStore.get(COOKIE_NAME)?.value;
+  if (!token) return null;
+
+  const session = await prisma.session.findUnique({
+    where: { token },
+    include: { user: true },
+  });
+  if (!session) return null;
+
+  return {
+    user: {
+      id: session.user.id,
+      name: session.user.name,
+      email: session.user.email,
+      image: session.user.image,
+    },
+  };
+}
+
+export async function requireAuth(): Promise<Session> {
+  const session = await getSession();
+  if (!session) redirect('/login');
+  return session;
+}
+
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session | null> {
+  const user = await prisma.user.findUnique({ where: { email } });
+  if (!user || user.password !== password) return null;
+
+  const token = crypto.randomUUID();
+  await prisma.session.create({
+    data: { token, userId: user.id },
+  });
+
+  const cookieStore = await cookies();
+  cookieStore.set(COOKIE_NAME, token, {
+    httpOnly: true,
+    path: '/',
+    sameSite: 'lax',
+  });
+
+  return {
+    user: {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      image: user.image,
+    },
+  };
+}
+
+export async function signOut(): Promise<void> {
+  const cookieStore = await cookies();
+  const token = cookieStore.get(COOKIE_NAME)?.value;
+  if (token) {
+    await prisma.session.deleteMany({ where: { token } });
+  }
+  cookieStore.delete(COOKIE_NAME);
+}
+```
+
+## Cookie Name
+
+The cookie name **must be `session-token`**. The CodeYam proxy uses this name for
+scenario auto-login (injecting/clearing the cookie when switching between scenarios).
+
+## API Routes
+
+### `/api/auth/login` (POST)
+
+```typescript
+import { signIn } from '@/app/lib/auth';
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+  const session = await signIn(email, password);
+  if (!session) {
+    return NextResponse.json({ error: 'Invalid credentials' }, { status: 401 });
+  }
+  return NextResponse.json({ user: session.user });
+}
+```
+
+### `/api/auth/logout` (POST)
+
+```typescript
+import { signOut } from '@/app/lib/auth';
+import { NextResponse } from 'next/server';
+
+export async function POST() {
+  await signOut();
+  return NextResponse.json({ success: true });
+}
+```
+
+### `/api/auth/session` (GET) — for client components
+
+```typescript
+import { getSession } from '@/app/lib/auth';
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const session = await getSession();
+  return NextResponse.json({ session });
+}
+```
+
+## Usage in Server Components
+
+```typescript
+import { getSession } from '@/app/lib/auth';
+
+export default async function Dashboard() {
+  const session = await getSession();
+  if (!session) redirect('/login');
+
+  return <h1>Welcome, {session.user.name}</h1>;
+}
+```
+
+## Usage in Client Components
+
+```typescript
+'use client';
+import { useEffect, useState } from 'react';
+
+export function UserNav() {
+  const [user, setUser] = useState(null);
+
+  useEffect(() => {
+    fetch('/api/auth/session')
+      .then(res => res.json())
+      .then(data => setUser(data.session?.user ?? null));
+  }, []);
+
+  if (!user) return <a href="/login">Sign In</a>;
+
+  return (
+    <div>
+      <span>{user.name}</span>
+      <button onClick={() => {
+        fetch('/api/auth/logout', { method: 'POST' })
+          .then(() => window.location.href = '/');
+      }}>
+        Sign Out
+      </button>
+    </div>
+  );
+}
+```
+
+## Login Page Pattern
+
+```typescript
+'use client';
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+
+export default function LoginPage() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const router = useRouter();
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    const res = await fetch('/api/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+    if (res.ok) {
+      router.push('/');
+      router.refresh();
+    } else {
+      setError('Invalid email or password');
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input type="email" value={email} onChange={e => setEmail(e.target.value)} placeholder="Email" required />
+      <input type="password" value={password} onChange={e => setPassword(e.target.value)} placeholder="Password" required />
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      <button type="submit">Sign In</button>
+    </form>
+  );
+}
+```
+
+## Seed Data for Scenarios
+
+When creating scenarios with auth, include both `User` and `Session` rows in seed data:
+
+```json
+{
+  "name": "Logged In User",
+  "type": "application",
+  "url": "/",
+  "seed": {
+    "user": [
+      {
+        "id": "user_1",
+        "name": "Alice",
+        "email": "alice@example.com",
+        "password": "password123"
+      }
+    ],
+    "session": [{ "id": "sess_1", "token": "sess_alice", "userId": "user_1" }]
+  },
+  "session": { "cookieValue": "sess_alice" }
+}
+```
+
+The top-level `"session"` field tells the proxy to set the `session-token` cookie,
+auto-logging the user in when this scenario is active.