npm - @codeyam/codeyam-cli - Versions diffs - 0.1.8 → 0.1.10 - Mend

@codeyam/codeyam-cli 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (343) hide show

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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","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 +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 CHANGED Viewed

@@ -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,23 @@ 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 real user prompt (before state file may exist).
+    # Save to a separate file so it persists across state transitions.
+    # Skip slash commands (e.g. /codeyam-editor) — they aren't user prompts.
+    if event_type == "user_prompt" and not os.path.exists(prompt_path):
+        prompt_text = event_data.get("prompt", "").strip()
+        if prompt_text and not prompt_text.startswith("/"):
+            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 +123,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 +130,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 +189,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 +207,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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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     |