npm - @codeyam/codeyam-cli - Versions diffs - 0.1.0-staging.a890816 → 0.1.0-staging.ad44cd3 - Mend

@codeyam/codeyam-cli 0.1.0-staging.a890816 → 0.1.0-staging.ad44cd3

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 (477) hide show

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

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

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