@codeyam/codeyam-cli 0.1.0-staging.415103 → 0.1.0-staging.435c1ad

package/codeyam-cli/templates/__tests__/editor-step-hook.prompt-capture.test.ts

@@ -0,0 +1,118 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+/**
+ * Tests for the prompt capture logic in editor-step-hook.py.
+ *
+ * The hook captures the user's feature request text on UserPromptSubmit events
+ * and writes it to `.codeyam/editor-user-prompt.txt`. This prompt is later
+ * recorded in the journal entry.
+ *
+ * The critical invariant: when a new feature starts (previous feature at step 18
+ * or no state file), the hook must overwrite the stale prompt from the previous
+ * feature — not skip writing because the file already exists.
+ */
+describe('editor-step-hook prompt capture', () => {
+  const hookPath = path.join(__dirname, '..', 'editor-step-hook.py');
+  let tmpDir: string;
+  let codeyamDir: string;
+  let promptPath: string;
+  let statePath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hook-prompt-test-'));
+    codeyamDir = path.join(tmpDir, '.codeyam');
+    fs.mkdirSync(codeyamDir, { recursive: true });
+    promptPath = path.join(codeyamDir, 'editor-user-prompt.txt');
+    statePath = path.join(codeyamDir, 'editor-step.json');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function runHook(input: object): string {
+    try {
+      return execFileSync('python3', [hookPath], {
+        input: JSON.stringify(input),
+        env: {
+          ...process.env,
+          CODEYAM_EDITOR_ACTIVE: '1',
+          CLAUDE_PROJECT_DIR: tmpDir,
+        },
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+    } catch (e: unknown) {
+      // Hook may exit with non-zero or produce stderr; capture stdout
+      return (e as { stdout?: string }).stdout || '';
+    }
+  }
+
+  function writeState(step: number, label: string): void {
+    fs.writeFileSync(
+      statePath,
+      JSON.stringify({ step, label, feature: 'Test Feature' }),
+    );
+  }
+
+  it('should capture the first user prompt when no prompt file exists', () => {
+    // No state file, no prompt file — brand new session
+    runHook({ prompt: 'CUJ 28 — Add author column to library table' });
+
+    expect(fs.existsSync(promptPath)).toBe(true);
+    expect(fs.readFileSync(promptPath, 'utf8')).toBe(
+      'CUJ 28 — Add author column to library table',
+    );
+  });
+
+  it('should NOT overwrite prompt during an active feature (step < 18)', () => {
+    // Feature in progress at step 5
+    writeState(5, 'Confirm');
+    fs.writeFileSync(promptPath, 'Original feature request');
+
+    runHook({ prompt: 'ok sounds good' });
+
+    expect(fs.readFileSync(promptPath, 'utf8')).toBe(
+      'Original feature request',
+    );
+  });
+
+  it('should overwrite stale prompt when previous feature is done (step >= 18)', () => {
+    // Previous feature completed (step 18), prompt file has stale content
+    writeState(18, 'Push');
+    fs.writeFileSync(promptPath, 'Previous feature request — STALE');
+
+    runHook({ prompt: 'CUJ 29 — User can write notes about articles' });
+
+    expect(fs.readFileSync(promptPath, 'utf8')).toBe(
+      'CUJ 29 — User can write notes about articles',
+    );
+  });
+
+  it('should overwrite stale prompt when no state file exists (between features)', () => {
+    // State file was cleared (between features), but prompt file persists
+    fs.writeFileSync(promptPath, 'Previous feature request — STALE');
+    // No state file — it was deleted
+
+    runHook({ prompt: 'CUJ 30 — New article highlights in collections' });
+
+    expect(fs.readFileSync(promptPath, 'utf8')).toBe(
+      'CUJ 30 — New article highlights in collections',
+    );
+  });
+
+  it('should NOT capture slash commands as user prompts', () => {
+    runHook({ prompt: '/codeyam-dev-mode' });
+
+    expect(fs.existsSync(promptPath)).toBe(false);
+  });
+
+  it('should NOT capture empty prompts', () => {
+    runHook({ prompt: '   ' });
+
+    expect(fs.existsSync(promptPath)).toBe(false);
+  });
+});

package/codeyam-cli/templates/chrome-extension-react/EXTENSION_SETUP.md

@@ -0,0 +1,75 @@
+# Chrome Extension Setup
+
+This project is a Chrome Extension built with React 19, TypeScript, Vite, and Tailwind CSS 4.
+
+## Development
+
+During development, the popup runs as a regular web page in the browser:
+
+```bash
+npm run dev
+```
+
+This starts a Vite dev server with hot reload. You can develop and test the popup
+UI in a normal browser tab — no need to load it as an extension during development.
+
+Data persistence uses `localStorage` in dev mode and `chrome.storage.local` when
+running as an actual extension (see `src/lib/storage.ts`).
+
+## Building the extension
+
+```bash
+npm run build:extension
+```
+
+This creates a `dist/` folder with the built extension. To load it in Chrome:
+
+1. Open `chrome://extensions/`
+2. Enable "Developer mode" (top right)
+3. Click "Load unpacked"
+4. Select the `dist/` folder
+
+## Project structure
+
+```
+src/
+  popup/         # Popup UI (React app shown when clicking the extension icon)
+    main.tsx     # Entry point
+    App.tsx      # Root component
+  background/    # Background service worker
+    service-worker.ts
+  lib/           # Shared utilities
+    storage.ts   # Type-safe chrome.storage wrapper with localStorage fallback
+  globals.css    # Global styles (Tailwind)
+public/
+  manifest.json  # Chrome extension manifest (Manifest V3)
+popup.html       # Popup HTML entry point (used by extension build)
+index.html       # Dev server entry point (same app, served as regular page)
+```
+
+## Key patterns
+
+- **Storage**: Import `storage` from `@/lib/storage` for data persistence.
+  It automatically uses `chrome.storage.local` in the extension and `localStorage`
+  during development.
+- **Popup size**: Set width/height on the root element in your popup component.
+  Chrome extension popups don't have a default size.
+- **Permissions**: Add any needed permissions to `public/manifest.json`.
+  Common ones: `storage`, `tabs`, `activeTab`, `alarms`.
+
+## Adding content scripts
+
+To inject scripts into web pages, add a `content_scripts` entry to `manifest.json`:
+
+```json
+{
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["content.js"]
+    }
+  ]
+}
+```
+
+Then create `src/content/content.ts` and add it as a Vite entry point.

package/codeyam-cli/templates/chrome-extension-react/README.md

@@ -0,0 +1,46 @@
+# Project Name
+
+Brief description of what this Chrome extension does.
+
+## Setup
+
+```bash
+npm run setup
+```
+
+## Development
+
+Start the dev server for local development:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) in your browser to preview the popup.
+
+## Build Extension
+
+Build the extension for Chrome:
+
+```bash
+npm run build:extension
+```
+
+Then load the `dist/` folder as an unpacked extension in `chrome://extensions`.
+
+## 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 Vite dev server     |
+| `npm run build`           | Build for production      |
+| `npm run build:extension` | Build as Chrome extension |

package/codeyam-cli/templates/chrome-extension-react/gitignore

@@ -0,0 +1,15 @@
+# dependencies
+/node_modules
+
+# build output
+/dist
+
+# misc
+.DS_Store
+
+# debug
+npm-debug.log*
+
+# env files
+.env
+.env*.local

package/codeyam-cli/templates/chrome-extension-react/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>CodeYam App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/popup/main.tsx"></script>
+  </body>
+</html>

package/codeyam-cli/templates/chrome-extension-react/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "codeyam-chrome-extension",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "setup": "npm install",
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "build:extension": "tsc -b && vite build --mode extension"
+  },
+  "dependencies": {
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4",
+    "@types/chrome": "^0.0.300",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@vitejs/plugin-react": "^4.4.1",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "vite": "^6.3.5"
+  }
+}

package/codeyam-cli/templates/chrome-extension-react/popup.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>CodeYam App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/popup/main.tsx"></script>
+  </body>
+</html>

package/codeyam-cli/templates/chrome-extension-react/public/manifest.json

@@ -0,0 +1,15 @@
+{
+  "manifest_version": 3,
+  "name": "CodeYam App",
+  "version": "0.1.0",
+  "description": "Built with CodeYam Editor",
+  "action": {
+    "default_popup": "popup.html",
+    "default_title": "CodeYam App"
+  },
+  "permissions": ["storage"],
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  }
+}

package/codeyam-cli/templates/chrome-extension-react/src/background/service-worker.ts

@@ -0,0 +1,7 @@
+// Background service worker for the Chrome extension.
+// This runs in the background and can handle events like
+// extension install, alarms, messages from popup/content scripts, etc.
+
+chrome.runtime.onInstalled.addListener(() => {
+  console.log('Extension installed');
+});

package/codeyam-cli/templates/chrome-extension-react/src/globals.css

@@ -0,0 +1,6 @@
+@import "tailwindcss";
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+}

package/codeyam-cli/templates/chrome-extension-react/src/lib/storage.ts

@@ -0,0 +1,37 @@
+// Wrapper around chrome.storage.local for type-safe data persistence.
+// Falls back to localStorage when running in a regular browser (during development).
+//
+// Usage:
+//   import { storage } from "@/lib/storage";
+//   await storage.get<Todo[]>("todos", []);
+//   await storage.set("todos", updatedTodos);
+
+const isChromeExtension =
+  typeof chrome !== 'undefined' && chrome.storage?.local;
+
+export const storage = {
+  async get<T>(key: string, defaultValue: T): Promise<T> {
+    if (isChromeExtension) {
+      const result = await chrome.storage.local.get(key);
+      return (result[key] as T) ?? defaultValue;
+    }
+    const item = localStorage.getItem(key);
+    return item ? (JSON.parse(item) as T) : defaultValue;
+  },
+
+  async set<T>(key: string, value: T): Promise<void> {
+    if (isChromeExtension) {
+      await chrome.storage.local.set({ [key]: value });
+      return;
+    }
+    localStorage.setItem(key, JSON.stringify(value));
+  },
+
+  async remove(key: string): Promise<void> {
+    if (isChromeExtension) {
+      await chrome.storage.local.remove(key);
+      return;
+    }
+    localStorage.removeItem(key);
+  },
+};

package/codeyam-cli/templates/chrome-extension-react/src/popup/App.tsx

@@ -0,0 +1,12 @@
+export default function App() {
+  return (
+    <main className="w-80 min-h-48 p-4 flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-xl font-bold mb-2">Welcome</h1>
+        <p className="text-gray-600 text-sm">
+          Your extension is ready. Start building!
+        </p>
+      </div>
+    </main>
+  );
+}

package/codeyam-cli/templates/chrome-extension-react/src/popup/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import '../globals.css';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/codeyam-cli/templates/chrome-extension-react/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/codeyam-cli/templates/chrome-extension-react/vite.config.ts

@@ -0,0 +1,41 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { resolve } from 'path';
+
+// In "extension" mode, build produces a Chrome extension in dist/.
+// In default mode, `vite dev` serves the popup as a regular web page
+// so you can develop and test it in a normal browser tab.
+
+export default defineConfig(({ mode }) => ({
+  plugins: [react(), tailwindcss()],
+  server: {
+    // Bind to the port provided by CodeYam editor (via PORT env var) or default 5173.
+    // Use 0.0.0.0 so the dev server is reachable on both IPv4 and IPv6 loopback.
+    port: process.env.PORT ? parseInt(process.env.PORT, 10) : 5173,
+    host: '0.0.0.0',
+  },
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  build:
+    mode === 'extension'
+      ? {
+          rollupOptions: {
+            input: {
+              popup: resolve(__dirname, 'popup.html'),
+            },
+            output: {
+              entryFileNames: '[name].js',
+              chunkFileNames: '[name].js',
+              assetFileNames: '[name].[ext]',
+            },
+          },
+          outDir: 'dist',
+          emptyOutDir: true,
+          copyPublicDir: true,
+        }
+      : undefined,
+}));

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

@@ -26,14 +26,22 @@ 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:
+**Name scenarios by data state** ("Rich Data", "Empty", "Mobile"), not by feature. When adding a feature, enhance an existing scenario's data — rename it if the scope has grown.
+
+**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","dimensions":["<name from screenSizes>"]}'
+
+# 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 +62,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 +78,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`.