@codeyam/codeyam-cli 0.1.0-staging.2a88920 → 0.1.0-staging.415103

package/codeyam-cli/templates/editor-step-hook.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+PostToolUse + Stop hook for editor mode step tracking.
+
+Reads .codeyam/editor-step.json and prints a reminder about the current step.
+Logs each firing to .codeyam/logs/editor-log.jsonl.
+If no state file exists, outputs nothing (not in editor mode or between features).
+"""
+
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+
+STEP_LABELS = {
+    1: "Plan",
+    2: "Prototype",
+    3: "Confirm",
+    4: "Deconstruct",
+    5: "Glossary",
+    6: "Analyze",
+    7: "App Scenarios",
+    8: "User Scenarios",
+    9: "Verify",
+    10: "Review",
+}
+
+STEP_RESTRICTIONS = {
+    1: "Do NOT write any code. Plan and describe only. Wait for user confirmation.",
+    2: "Do NOT create scenarios or run codeyam analyze. Build fast — working prototype with real data.",
+    3: "Present a selection menu (AskUserQuestion) for confirmation. Do NOT refactor or create scenarios until approved.",
+    4: "Do NOT create scenarios. Write a failing test FIRST, then extract. TDD only.",
+    5: "Do NOT write application code or scenarios. Update the glossary only.",
+    6: "Run codeyam analyze for each file. Verify all pass. Fix any failures before proceeding.",
+    7: "Do NOT modify application code. Create and register app-level scenarios only.",
+    8: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
+    9: "Verify entity screenshots (/api/editor-entity-status) AND editor scenarios. After ANY code fix, re-run codeyam analyze on affected files. Fix only — do NOT add features.",
+    10: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors), then present selection menu (AskUserQuestion): Save or make changes.",
+}
+
+
+def log_event(project_dir, event, data=None):
+    """Append a JSONL entry to .codeyam/logs/editor-log.jsonl."""
+    try:
+        logs_dir = os.path.join(project_dir, ".codeyam", "logs")
+        os.makedirs(logs_dir, exist_ok=True)
+        log_path = os.path.join(logs_dir, "editor-log.jsonl")
+        entry = {"ts": datetime.now(timezone.utc).isoformat(), "event": event}
+        if data:
+            entry.update(data)
+        with open(log_path, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+    except Exception:
+        pass  # Logging is best-effort
+
+
+def detect_event():
+    """Detect whether this is a PostToolUse or Stop hook from stdin."""
+    try:
+        raw = sys.stdin.read()
+        if not raw.strip():
+            return "unknown", {}
+        data = json.loads(raw)
+        # PostToolUse has tool_name; Stop has stop_hook_active
+        if "tool_name" in data:
+            return "post_tool_use", data
+        elif "stop_hook_active" in data:
+            return "stop", data
+        return "unknown", data
+    except Exception:
+        return "unknown", {}
+
+
+def main():
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
+
+    if not os.path.exists(state_path):
+        return
+
+    try:
+        with open(state_path, "r") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return
+
+    step = state.get("step")
+    label = state.get("label", "Unknown")
+    feature = state.get("feature", "")
+
+    if not step:
+        return
+
+    event_type, event_data = detect_event()
+
+    # Log the hook firing
+    log_data = {"step": step, "label": label, "feature": feature, "hook": event_type}
+    if event_type == "post_tool_use":
+        log_data["tool"] = event_data.get("tool_name", "")
+    log_event(project_dir, "hook", log_data)
+
+    restriction = STEP_RESTRICTIONS.get(step, "")
+    next_cmd = f"codeyam editor {step + 1}" if step < 10 else "codeyam editor 1"
+
+    lines = [
+        f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
+    ]
+    if restriction:
+        lines.append(restriction)
+
+    if event_type == "stop":
+        # Build colored progress tracker using ANSI escape codes
+        GREEN = "\033[32m"
+        BOLD_CYAN = "\033[1;36m"
+        DIM = "\033[2m"
+        RESET = "\033[0m"
+        tracker = [f"{DIM}  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510{RESET}"]
+        for i in range(1, 11):
+            lbl = STEP_LABELS[i].ljust(28)
+            num = f" {i}" if i < 10 else f"{i}"
+            content = f"{num}. {lbl}"
+            if i < step:
+                tracker.append(f"{DIM}  \u2502{RESET}{GREEN}  \u2713  {content}{RESET}{DIM}\u2502{RESET}")
+            elif i == step:
+                tracker.append(f"{DIM}  \u2502{RESET}{BOLD_CYAN}  \u2192  {content}{RESET}{DIM}\u2502{RESET}")
+            else:
+                tracker.append(f"{DIM}  \u2502  \u25cb  {content}\u2502{RESET}")
+        tracker.append(f"{DIM}  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518{RESET}")
+        lines.append("Present this progress tracker to the user (copy verbatim):")
+        lines.extend(tracker)
+        lines.append(
+            "For the CURRENT step (\u2192), show each checklist item with "
+            "\u2713 (done) or \u2717 (skipped + reason)."
+        )
+
+    lines.append(f"When this step is complete, run: {next_cmd}")
+
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()

package/codeyam-cli/templates/hooks/staleness-check.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Staleness check hook - runs after file edits to check if related rules need review
+# Receives JSON input via stdin with tool info
+
+set -e
+
+# Read the input JSON
+INPUT=$(cat)
+
+# Extract the file path that was edited
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0  # No file path, nothing to check
+fi
+
+# Find rules that match this file path
+RULES_DIR="${CLAUDE_PROJECT_DIR}/.claude/rules"
+
+if [ ! -d "$RULES_DIR" ]; then
+  exit 0  # No rules directory
+fi
+
+# Search for rules whose paths might match the edited file
+MATCHING_RULES=""
+while IFS= read -r -d '' rule_file; do
+  # Extract paths from frontmatter
+  PATHS=$(sed -n '/^---$/,/^---$/p' "$rule_file" | grep -E "^\s*-\s*'" | sed "s/.*'\(.*\)'.*/\1/")
+
+  for pattern in $PATHS; do
+    # Simple check if the file might match the pattern
+    if [[ "$FILE_PATH" == *"${pattern%%\**}"* ]]; then
+      MATCHING_RULES="$MATCHING_RULES\n- $(basename "$rule_file")"
+      break
+    fi
+  done
+done < <(find "$RULES_DIR" -name "*.md" -print0 2>/dev/null)
+
+if [ -n "$MATCHING_RULES" ]; then
+  echo "📋 Modified file may have related rules that need review:$MATCHING_RULES"
+fi
+
+exit 0

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/PRISMA_SETUP.md

@@ -0,0 +1,84 @@
+# Prisma 7 + SQLite Setup
+
+This project uses Prisma 7 with SQLite via the `better-sqlite3` driver adapter.
+
+## How it works
+
+Prisma 7 requires a **driver adapter** — you cannot use `new PrismaClient()` alone.
+Every file that creates a PrismaClient must use this pattern:
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3';
+
+const adapter = new PrismaBetterSqlite3({ url: 'file:./dev.db' });
+const prisma = new PrismaClient({ adapter });
+```
+
+The singleton in `app/lib/prisma.ts` is already configured. Import it in your code:
+
+```typescript
+import { prisma } from '@/app/lib/prisma';
+```
+
+## 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 `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.
+
+## 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
+npx tsx prisma/seed.ts
+# or: npm run db:seed
+
+# Reset the database (delete + recreate + seed)
+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);
+}
+```

package/codeyam-cli/templates/nextjs-prisma-sqlite/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);
+}