@codeyam/codeyam-cli 0.1.8 → 0.1.9

package/codeyam-cli/templates/codeyam-editor-claude.md

@@ -26,14 +26,20 @@ A **scenario** is a named set of data that drives how the app renders. Scenarios
 - **App-level scenarios**: Full application state — what the database contains, what API responses return. Example: "Empty Dashboard", "Dashboard with 50 Tasks", "Dashboard with Overdue Tasks"
 - **Component-level scenarios**: Props for a single component in isolation. Example: "TaskCard - Default", "TaskCard - Overdue", "TaskCard - Completed"
 
-**Always register scenarios with CodeYam** after creating them:
+**Only create scenarios for states the current code can render.** If you seed 10 articles but the app doesn't have an article list component yet, the screenshot will show an empty page — that's a broken scenario. After registering, always view the captured screenshot to verify the data is actually visible.
+
+**Always register scenarios with CodeYam** using the CLI:
 
 ```bash
-curl -s -X POST http://localhost:${CODEYAM_PORT:-3111}/api/editor-register-scenario \
-  -H 'Content-Type: application/json' \
-  -d '{"name": "...", "componentName": "...", "zoomLevel": "component", "mockData": {...}}'
+# Small inline JSON:
+codeyam editor register '{"name":"TaskCard - Default","componentName":"TaskCard","url":"/isolated-components/TaskCard?s=Default"}'
+
+# Large JSON — use the Write tool to write to .codeyam/tmp/scenario.json, then:
+codeyam editor register @.codeyam/tmp/scenario.json
 ```
 
+**To list existing scenarios:** `codeyam editor scenarios`
+
 ### Database First
 
 Use a real database (SQLite + Prisma recommended) from the start. This lets scenarios represent different database states rather than just static prop variations:
@@ -54,7 +60,11 @@ Build components so they work at both zoom levels. A `TaskCard` should render co
 ## Workflow
 
 1. Build a component
-2. Create 2-3 scenarios for it (happy path, empty state, edge case)
+2. Create scenarios with rich, realistic data that thoroughly exercises the component:
+   - Happy path with diverse, realistic content (not just "Test Item 1", "Test Item 2")
+   - Empty state (no data, first-time user)
+   - Rich data (many items, all optional fields populated, varied lengths and categories)
+   - Edge cases if they surface naturally from diverse data
 3. Register the scenarios with CodeYam
 4. Preview each scenario to verify the component handles all states
 5. Repeat for the next component, building up scenario coverage
@@ -66,3 +76,72 @@ Build components so they work at both zoom levels. A `TaskCard` should render co
 - Components accept props that can be provided by scenarios
 - Database seed scripts go in `prisma/seeds/` (one per scenario when using DB-level scenarios)
 - MSW handler files go in `.codeyam/msw-handlers/` (one per scenario for API mocking)
+
+## Design System
+
+If `.codeyam/design-system.md` exists, it contains the project's design tokens and brand guidelines. The editor step instructions will automatically show its contents inline — you don't need to read the file separately.
+
+- Define **every** design token as a CSS custom property in `globals.css` — not just colors:
+  - Colors: `--bg-surface`, `--text-primary`, `--accent-green-a`, etc.
+  - Typography: `--text-xs: 12px`, `--text-sm: 14px`, `--text-lg: 18px`, etc.
+  - Font weights: `--font-weight-normal: 400`, `--font-weight-medium: 500`, `--font-weight-semibold: 600`
+  - Spacing: `--spacing-xs: 4px`, `--spacing-sm: 8px`, `--spacing-md: 12px`, `--spacing-lg: 16px`, etc.
+  - Border radius, shadows, and transitions
+- Components must reference tokens — **zero hardcoded px values** for font-size, padding, margin, gap, or colors
+  - Bad: `fontSize: 14`, `padding: '12px 16px'`, `gap: 8`
+  - Good: `fontSize: 'var(--text-sm)'`, `padding: 'var(--spacing-md) var(--spacing-lg)'`, `gap: 'var(--spacing-sm)'`
+- This ensures the entire app updates when the design system changes
+
+## Avoiding Permission Prompts
+
+These patterns cause unnecessary approval prompts in Claude Code. Follow these rules:
+
+### Writing JSON files — use the Write tool, not bash
+
+**BAD** (triggers "expansion obfuscation" security warning due to braces+quotes in heredoc):
+
+```bash
+cat > /tmp/scenario.json << 'EOF'
+{"name":"My Scenario","localStorage":{"key":"[{\"id\":\"1\"}]"}}
+EOF
+```
+
+**GOOD** (Write tool is pre-approved, no bash prompt):
+Use the **Write tool** to create `.codeyam/tmp/scenario.json`, then register:
+
+```bash
+codeyam editor register @.codeyam/tmp/scenario.json
+```
+
+### Listing scenarios — use the CLI subcommand
+
+**BAD** (triggers bash approval):
+
+```bash
+cat .codeyam/editor-scenarios/*.json | grep -o '"name":"[^"]*"'
+ls .codeyam/editor-scenarios/*.json
+```
+
+**GOOD** (pre-approved):
+
+```bash
+codeyam editor scenarios
+```
+
+### Database schema changes — never force-reset
+
+**BAD** (destructive, triggers approval, drops all data):
+
+```bash
+npx prisma db push --force-reset
+```
+
+**GOOD** (preserves data by providing defaults for new required columns):
+
+```prisma
+userId Int @default(0)   // existing rows get 0
+```
+
+Then: `npm run db:push`
+
+If you must add a required column without a default, make it optional (`Int?`) or provide a `@default()` value. Never destroy user data with `--force-reset`.

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-PostToolUse + Stop hook for editor mode step tracking.
+PostToolUse + Stop + UserPromptSubmit 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.
@@ -26,6 +26,10 @@ STEP_LABELS = {
     10: "Verify",
     11: "Journal",
     12: "Review",
+    13: "Present",
+    14: "Commit",
+    15: "Finalize",
+    16: "Push",
 }
 
 STEP_RESTRICTIONS = {
@@ -40,7 +44,11 @@ STEP_RESTRICTIONS = {
     9: "Do NOT modify application code. Create user-persona scenarios only (or skip if no users).",
     10: "Verify component isolation screenshots AND editor scenarios. After ANY code fix, re-register affected components. Fix only — do NOT add features.",
     11: "Create or update the journal entry for this feature. Do NOT create a duplicate — check if one exists first.",
-    12: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors), then present selection menu (AskUserQuestion): Save or make changes.",
+    12: "Verify ALL screenshots exist and NO client-side errors (/api/editor-client-errors). Run codeyam editor audit. Do not proceed until all checks pass.",
+    13: "Show the results panel, present summary, then selection menu (AskUserQuestion): Save or make changes.",
+    14: "Hide the results panel and commit all changes. Do NOT push — that happens in step 16.",
+    15: "Update the journal entry with the commit SHA and amend the commit to include the journal update.",
+    16: "Check for a git remote and offer to push. WAIT for the user's answer before starting the next feature.",
 }
 
 
@@ -60,17 +68,19 @@ def log_event(project_dir, event, data=None):
 
 
 def detect_event():
-    """Detect whether this is a PostToolUse or Stop hook from stdin."""
+    """Detect whether this is a PostToolUse, Stop, or UserPromptSubmit 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
+        # PostToolUse has tool_name; Stop has stop_hook_active; UserPromptSubmit has prompt
         if "tool_name" in data:
             return "post_tool_use", data
         elif "stop_hook_active" in data:
             return "stop", data
+        elif "prompt" in data:
+            return "user_prompt", data
         return "unknown", data
     except Exception:
         return "unknown", {}
@@ -79,6 +89,22 @@ def detect_event():
 def main():
     project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
     state_path = os.path.join(project_dir, ".codeyam", "editor-step.json")
+    prompt_path = os.path.join(project_dir, ".codeyam", "editor-user-prompt.txt")
+
+    # Detect event early so we can capture the user prompt even before state exists
+    event_type, event_data = detect_event()
+
+    # Capture the very first user prompt (before state file may exist).
+    # Save to a separate file so it persists across state transitions.
+    if event_type == "user_prompt" and not os.path.exists(prompt_path):
+        prompt_text = event_data.get("prompt", "").strip()
+        if prompt_text:
+            try:
+                os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+                with open(prompt_path, "w") as f:
+                    f.write(prompt_text)
+            except Exception:
+                pass  # Best-effort
 
     if not os.path.exists(state_path):
         return
@@ -96,8 +122,6 @@ def main():
     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":
@@ -105,7 +129,51 @@ def main():
     log_event(project_dir, "hook", log_data)
 
     restriction = STEP_RESTRICTIONS.get(step, "")
-    next_cmd = f"codeyam editor {step + 1}" if step < 12 else "codeyam editor 1"
+    next_cmd = f"codeyam editor {step + 1}" if step < 16 else "codeyam editor 1"
+
+    # UserPromptSubmit: concise workflow reminder injected before Claude processes the user's message
+    if event_type == "user_prompt":
+        lines = [
+            f'<user-prompt-submit-hook>',
+            f'Editor Mode — Step {step} ({label}): "{feature}"',
+        ]
+
+        # Include the active scenario so Claude knows what the user is looking at
+        active_scenario_path = os.path.join(project_dir, ".codeyam", "active-scenario.json")
+        try:
+            with open(active_scenario_path, "r") as f:
+                active = json.load(f)
+            scenario_name = (
+                active.get("scenarioName")
+                or active.get("scenarioSlug", "").replace("_", " ")
+            )
+            if scenario_name:
+                lines.append(
+                    f'The user is currently viewing scenario: "{scenario_name}". '
+                    "Assume any feedback refers to this scenario unless they say otherwise."
+                )
+        except (IOError, json.JSONDecodeError):
+            pass
+
+        if step in (13, 14, 15, 16):
+            lines.append(
+                "If the user is requesting changes (even indirectly), "
+                "run `codeyam editor change` BEFORE making any modifications "
+                "(code, scenarios, data, styles — everything). "
+                "The change command gives you the post-change checklist. "
+                "The change workflow ensures Working Session Results are shown to the user. "
+                "If the user chose to commit, run `codeyam editor 14` to advance to the commit step."
+            )
+        else:
+            lines.append(
+                f"You are on step {step}. Follow the `codeyam editor` workflow. "
+                f"Do NOT skip ahead or make changes outside the current step."
+            )
+        if restriction:
+            lines.append(restriction)
+        lines.append('</user-prompt-submit-hook>')
+        print("\n".join(lines))
+        return
 
     lines = [
         f'Editor Mode \u2014 Step {step} ({label}): "{feature}"',
@@ -120,7 +188,7 @@ def main():
         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, 13):
+        for i in range(1, 17):
             lbl = STEP_LABELS[i].ljust(28)
             num = f" {i}" if i < 10 else f"{i}"
             content = f"{num}. {lbl}"
@@ -138,6 +206,27 @@ def main():
             "\u2713 (done) or \u2717 (skipped + reason)."
         )
 
+    if event_type == "stop" and step in (13, 14):
+        import subprocess as _sp
+        try:
+            _result = _sp.run(
+                ["git", "status", "--porcelain"],
+                cwd=project_dir,
+                capture_output=True, text=True, timeout=5
+            )
+            has_uncommitted = bool(_result.stdout.strip())
+        except Exception:
+            has_uncommitted = False
+
+        if has_uncommitted:
+            lines.append(
+                "\n\033[1;31m⚠️  You have uncommitted changes but haven't shown Working Session Results.\033[0m"
+            )
+            lines.append(
+                "\033[31mRun `codeyam editor change` if you haven't already, then complete the "
+                "checklist and run `codeyam editor 13` to show results to the user.\033[0m"
+            )
+
     lines.append(f"When this step is complete, run: {next_cmd}")
 
     print("\n".join(lines))

package/codeyam-cli/templates/expo-react-native/MOBILE_SETUP.md

@@ -0,0 +1,89 @@
+# Expo + React Native Setup
+
+## Development
+
+This project uses **Expo** with **Expo Router** for file-based navigation and **NativeWind** (Tailwind CSS) for styling.
+
+### Web Development (used by CodeYam)
+
+```bash
+npm run dev
+```
+
+This starts the Expo web dev server. CodeYam uses this to preview your app and take screenshots.
+
+### Mobile Development
+
+```bash
+# iOS Simulator
+npm run ios
+
+# Android Emulator
+npm run android
+
+# Start Expo dev server (pick platform from menu)
+npm start
+```
+
+## Project Structure
+
+```
+app/                    # Expo Router file-based routes
+  _layout.tsx           # Root layout (status bar, navigation)
+  (tabs)/               # Tab-based navigation group
+    _layout.tsx         # Tab bar configuration
+    index.tsx           # Home tab
+    settings.tsx        # Settings tab
+components/             # Reusable components
+lib/
+  storage.ts            # AsyncStorage wrapper for persistent data
+```
+
+## Key Patterns
+
+### Navigation (Expo Router)
+
+Add new screens by creating files in `app/`:
+
+- `app/profile.tsx` — accessible at `/profile`
+- `app/items/[id].tsx` — dynamic route at `/items/123`
+
+### Data Fetching
+
+Use standard `fetch()` for API calls. CodeYam intercepts these to provide mock data during simulations:
+
+```tsx
+const response = await fetch('/api/items');
+const data = await response.json();
+```
+
+### Storage
+
+Use the typed storage helper for persistent data:
+
+```tsx
+import { storage } from '@/lib/storage';
+
+const items = await storage.get('items', []);
+await storage.set('items', [...items, newItem]);
+```
+
+### Styling (NativeWind)
+
+Use Tailwind classes on React Native components:
+
+```tsx
+<View className="flex-1 items-center justify-center bg-white p-4">
+  <Text className="text-lg font-bold text-gray-900">Hello</Text>
+</View>
+```
+
+## Building for Production
+
+```bash
+# Web
+npm run build:web
+
+# iOS/Android (requires EAS CLI)
+npx eas build
+```

package/codeyam-cli/templates/expo-react-native/README.md

@@ -0,0 +1,41 @@
+# Project Name
+
+Brief description of what this app does.
+
+## Setup
+
+```bash
+npm run setup
+```
+
+## Development
+
+Start the Expo dev server (web):
+
+```bash
+npm run dev
+```
+
+For native platforms:
+
+```bash
+npm run ios      # iOS simulator
+npm run android  # Android emulator
+```
+
+## Using CodeYam Editor
+
+This project was built with [CodeYam](https://codeyam.com). To launch the editor:
+
+```bash
+codeyam editor
+```
+
+## Scripts
+
+| Script            | Description                 |
+| ----------------- | --------------------------- |
+| `npm run setup`   | Install dependencies        |
+| `npm run dev`     | Start Expo dev server (web) |
+| `npm run ios`     | Run on iOS simulator        |
+| `npm run android` | Run on Android emulator     |

package/codeyam-cli/templates/expo-react-native/app/(tabs)/_layout.tsx

@@ -0,0 +1,33 @@
+import { Tabs } from 'expo-router';
+import { Ionicons } from '@expo/vector-icons';
+
+export default function TabLayout() {
+  return (
+    <Tabs
+      screenOptions={{
+        tabBarActiveTintColor: '#005C75',
+        headerStyle: { backgroundColor: '#f8fafc' },
+        headerTitleStyle: { fontWeight: '600' },
+      }}
+    >
+      <Tabs.Screen
+        name="index"
+        options={{
+          title: 'Home',
+          tabBarIcon: ({ color, size }) => (
+            <Ionicons name="home-outline" size={size} color={color} />
+          ),
+        }}
+      />
+      <Tabs.Screen
+        name="settings"
+        options={{
+          title: 'Settings',
+          tabBarIcon: ({ color, size }) => (
+            <Ionicons name="settings-outline" size={size} color={color} />
+          ),
+        }}
+      />
+    </Tabs>
+  );
+}

package/codeyam-cli/templates/expo-react-native/app/(tabs)/index.tsx

@@ -0,0 +1,12 @@
+import { View, Text } from 'react-native';
+
+export default function HomeScreen() {
+  return (
+    <View className="flex-1 items-center justify-center bg-white p-6">
+      <Text className="text-2xl font-bold text-gray-900 mb-2">Welcome</Text>
+      <Text className="text-base text-gray-500 text-center">
+        Your Expo app is ready. Start building!
+      </Text>
+    </View>
+  );
+}

package/codeyam-cli/templates/expo-react-native/app/(tabs)/settings.tsx

@@ -0,0 +1,12 @@
+import { View, Text } from 'react-native';
+
+export default function SettingsScreen() {
+  return (
+    <View className="flex-1 items-center justify-center bg-white p-6">
+      <Text className="text-2xl font-bold text-gray-900 mb-2">Settings</Text>
+      <Text className="text-base text-gray-500 text-center">
+        Configure your app preferences here.
+      </Text>
+    </View>
+  );
+}

package/codeyam-cli/templates/expo-react-native/app/_layout.tsx

@@ -0,0 +1,12 @@
+import '../global.css';
+import { Stack } from 'expo-router';
+import { StatusBar } from 'expo-status-bar';
+
+export default function RootLayout() {
+  return (
+    <>
+      <Stack screenOptions={{ headerShown: false }} />
+      <StatusBar style="auto" />
+    </>
+  );
+}

package/codeyam-cli/templates/expo-react-native/app.json

@@ -0,0 +1,18 @@
+{
+  "expo": {
+    "name": "CodeYam Expo App",
+    "slug": "codeyam-expo-app",
+    "version": "1.0.0",
+    "scheme": "codeyam-expo-app",
+    "platforms": ["ios", "android", "web"],
+    "web": {
+      "bundler": "metro",
+      "output": "single",
+      "favicon": "./assets/favicon.png"
+    },
+    "plugins": ["expo-router"],
+    "experiments": {
+      "typedRoutes": true
+    }
+  }
+}

package/codeyam-cli/templates/expo-react-native/babel.config.js

@@ -0,0 +1,9 @@
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: [
+      ['babel-preset-expo', { jsxImportSource: 'nativewind' }],
+      'nativewind/babel',
+    ],
+  };
+};

package/codeyam-cli/templates/expo-react-native/gitignore

@@ -0,0 +1,12 @@
+node_modules/
+.expo/
+dist/
+web-build/
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+*.orig.*
+.env
+.env.local

package/codeyam-cli/templates/expo-react-native/global.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/codeyam-cli/templates/expo-react-native/lib/storage.ts

@@ -0,0 +1,32 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+/**
+ * Type-safe storage abstraction over AsyncStorage.
+ * Works on iOS, Android, and Web.
+ */
+export const storage = {
+  async get<T>(key: string, defaultValue: T): Promise<T> {
+    try {
+      const raw = await AsyncStorage.getItem(key);
+      return raw !== null ? JSON.parse(raw) : defaultValue;
+    } catch {
+      return defaultValue;
+    }
+  },
+
+  async set<T>(key: string, value: T): Promise<void> {
+    try {
+      await AsyncStorage.setItem(key, JSON.stringify(value));
+    } catch {
+      // Storage write failed silently
+    }
+  },
+
+  async remove(key: string): Promise<void> {
+    try {
+      await AsyncStorage.removeItem(key);
+    } catch {
+      // Storage remove failed silently
+    }
+  },
+};

package/codeyam-cli/templates/expo-react-native/metro.config.js

@@ -0,0 +1,6 @@
+const { getDefaultConfig } = require('expo/metro-config');
+const { withNativeWind } = require('nativewind/metro');
+
+const config = getDefaultConfig(__dirname);
+
+module.exports = withNativeWind(config, { input: './global.css' });

package/codeyam-cli/templates/expo-react-native/nativewind-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="nativewind/types" />

package/codeyam-cli/templates/expo-react-native/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "codeyam-expo-app",
+  "version": "0.1.0",
+  "private": true,
+  "main": "expo-router/entry",
+  "scripts": {
+    "setup": "npm install",
+    "dev": "expo start --web",
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "build:web": "expo export --platform web"
+  },
+  "dependencies": {
+    "expo": "~55.0.5",
+    "expo-router": "~55.0.4",
+    "expo-status-bar": "~55.0.4",
+    "expo-linking": "~55.0.7",
+    "expo-constants": "~55.0.7",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "react-native": "0.83.2",
+    "react-native-web": "^0.21.0",
+    "react-native-safe-area-context": "~5.6.2",
+    "react-native-screens": "~4.23.0",
+    "@react-navigation/native": "^7.1.33",
+    "@expo/vector-icons": "^15.0.2",
+    "@react-native-async-storage/async-storage": "2.2.0",
+    "nativewind": "^4.2.2",
+    "tailwindcss": "^3.4.19",
+    "react-native-reanimated": "4.2.1"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.2",
+    "babel-preset-expo": "^55.0.10",
+    "typescript": "~5.9.2"
+  }
+}

package/codeyam-cli/templates/expo-react-native/tailwind.config.js

@@ -0,0 +1,10 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: 'class',
+  content: ['./app/**/*.{js,jsx,ts,tsx}', './components/**/*.{js,jsx,ts,tsx}'],
+  presets: [require('nativewind/preset')],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};

package/codeyam-cli/templates/expo-react-native/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "expo/tsconfig.base",
+  "compilerOptions": {
+    "strict": true,
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
+}