@codeyam/codeyam-cli 0.1.0-staging.4057bd2 → 0.1.0-staging.435c1ad

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

@@ -0,0 +1,216 @@
+# .codeyam/ Directory Reference
+
+This file documents the `.codeyam/` internals and CLI commands. Consult this when you're stuck on scenario registration, audit failures, preview issues, or understanding what files do what.
+
+## Directory Structure
+
+### Committed Files (shared across clones)
+
+- `config.json` — Project configuration: slug, screen sizes, default viewport, feature metadata
+- `editor-scenarios/` — Scenario JSON files with seed data, localStorage, MSW handlers, and metadata
+- `scenarios-manifest.json` — Index of all scenarios for database sync on fresh clones
+- `design-system.md` — Design tokens and brand guidelines (if present)
+- `glossary.json` — Entity glossary built during extraction steps
+- `msw-handlers/` — MSW handler files for API mocking (one per scenario)
+- `seed-adapters/` — Seed adapter templates for database seeding
+
+### Gitignored Files (machine-local)
+
+- `db.sqlite3` / `db.sqlite3-wal` / `db.sqlite3-shm` — SQLite database (rebuilt on clone via `codeyam editor`)
+- `secrets.json` — API keys (Anthropic, etc.)
+- `server.json` / `server-state.json` — Background server process state
+- `queue.json` — Analysis job queue state
+- `active-scenario.json` — Currently active scenario for the preview
+- `editor-step.json` — Current editor workflow step number
+- `editor-user-prompt.txt` — The user's feature request text
+- `claude-session-id.txt` — Claude Code session ID for step tracking
+- `editor-mode-context.md` / `dev-mode-context.md` — Generated context for Claude
+- `logs/` — Server and analysis logs
+- `llm-calls/` — LLM call recordings
+- `captures/` — Playwright screenshot captures
+- `results/` — Analysis results
+- `tmp/` — Temporary files (use for large scenario JSON)
+- `rules/` — Auto-installed Claude rules
+- `bin/` — Helper scripts and hooks
+
+## CLI Command Reference
+
+All commands use the pattern `codeyam editor <subcommand>`.
+
+### Scenario Management
+
+| Command                                 | Description                                                |
+| --------------------------------------- | ---------------------------------------------------------- |
+| `codeyam editor register '<json>'`      | Register a scenario (inline JSON or `@path/to/file.json`)  |
+| `codeyam editor scenarios`              | List all registered scenarios                              |
+| `codeyam editor delete <scenarioId>`    | Delete a scenario by ID                                    |
+| `codeyam editor scenario-coverage`      | Verify all affected scenarios are fresh after code changes |
+| `codeyam editor validate-seed '<json>'` | Validate seed data structure                               |
+
+### Preview & Verification
+
+| Command                           | Description                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `codeyam editor preview '<json>'` | Navigate preview — **must include `dimension`** (e.g., `{"path":"/route","dimension":"Desktop"}`) |
+| `codeyam editor client-errors`    | Show client-side errors from the preview iframe                                                   |
+| `codeyam editor audit`            | Check that glossary entries have registered scenarios and tests                                   |
+
+### Entity Analysis
+
+| Command                                          | Description                                                            |
+| ------------------------------------------------ | ---------------------------------------------------------------------- |
+| `codeyam editor analyze-imports [file...]`       | Build the import dependency graph (optionally scope to specific files) |
+| `codeyam editor dependents <EntityName>`         | Find all entities that import a given entity                           |
+| `codeyam editor isolate "ComponentA ComponentB"` | Create isolation route directories for components                      |
+
+### Server
+
+| Command                     | Description             |
+| --------------------------- | ----------------------- |
+| `codeyam editor dev-server` | Query dev server status |
+
+### Workflow
+
+| Command                                                 | Description                                                     |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| `codeyam editor <1-18>`                                 | Jump to a specific editor workflow step                         |
+| `codeyam editor steps`                                  | Show setup overview or cycle progress                           |
+| `codeyam editor change <feature>`                       | Start the change workflow for modifying features                |
+| `codeyam editor sync`                                   | Import scenarios from manifest into database (used after clone) |
+| `codeyam editor migrate [step\|next\|complete\|status]` | Run migration workflow steps                                    |
+
+## Scenario Registration Patterns
+
+### Component-Level Scenario
+
+```json
+{
+  "name": "TaskCard - Overdue",
+  "componentName": "TaskCard",
+  "url": "/isolated-components/TaskCard?s=Overdue",
+  "dimensions": ["Desktop"]
+}
+```
+
+### App-Level Scenario
+
+```json
+{
+  "name": "Dashboard with Tasks",
+  "url": "/",
+  "dimensions": ["Desktop"],
+  "seedData": {
+    "tasks": [{ "id": 1, "title": "Ship feature", "status": "in_progress" }]
+  },
+  "localStorage": { "user": "{\"name\":\"Alice\"}" }
+}
+```
+
+### Large JSON — Use a Tmp File
+
+Write JSON to `.codeyam/tmp/scenario.json` using the **Write tool**, then:
+
+```bash
+codeyam editor register @.codeyam/tmp/scenario.json
+```
+
+### Re-registration
+
+Registering a scenario with the same name replaces the existing one. No need to delete first.
+
+### Dimensions
+
+Dimension names come from `screenSizes` in `.codeyam/config.json`. Common values: `"Desktop"`, `"Mobile"`, `"Tablet"`. Every scenario and preview command must specify a dimension.
+
+## Troubleshooting
+
+### Audit gate blocking step 8+
+
+The audit checks that every glossary entity has at least one scenario and passes tests. Fix by:
+
+1. Run `codeyam editor audit` to see which entities are missing coverage
+2. Register scenarios for uncovered entities
+3. Fix any failing tests
+4. Re-run audit — do NOT loop `audit` and `analyze-imports` repeatedly
+
+### Scenarios showing empty/blank pages or error pages
+
+The scenario renders a URL but the page has no visible content, or shows an error page. Common causes:
+
+- **URL references IDs that don't exist in the seed data**: The URL contains a dynamic segment (e.g., `/items/abc-123`) but the seed data creates records with different IDs. Check the register output for `API response error` lines — they show the exact API call that failed and the server's response.
+- **Seed data doesn't match the code**: The seeded data has fields the component doesn't read, or the component expects data the seed doesn't provide
+- **Missing API route**: The component fetches from an API that doesn't exist yet
+- **Component not exported or not mounted**: The isolation route doesn't render the component
+- **Only create scenarios for states the current code can render** — if the component isn't built yet, the screenshot will be blank
+
+### Client errors in preview
+
+Run `codeyam editor client-errors` to see errors from the preview. There are three types:
+
+- **Console errors** (`Page console.error:`): JavaScript runtime errors — missing env vars, import errors, schema mismatches
+- **HTTP errors** (`HTTP error: status=NNN`): The page URL itself returned a non-2xx status (e.g., 404 page not found)
+- **API response errors** (`API response error: GET /api/... → NNN`): An API call made during page load returned a non-2xx status, with the server's response body included
+
+API response errors are the most actionable — they show the exact endpoint that failed and what the server returned. When you see one, read the scenario's seed data and verify that the IDs in the URL match IDs created by the seed. For example, if the URL is `/page/items/abc-123` but the seed creates items with ID `item-1`, the API call to `/api/items/abc-123` will return 404.
+
+### Dependents returning nothing
+
+`codeyam editor dependents <Entity>` requires the import graph to be built first. Run:
+
+```bash
+codeyam editor analyze-imports                           # all entities
+codeyam editor analyze-imports app/components/Foo.tsx    # single file
+codeyam editor analyze-imports app/components/Foo.tsx app/components/Bar.tsx  # multiple files
+```
+
+Then retry `dependents`. The import graph persists in the database.
+
+### Database missing after clone
+
+This is expected — `db.sqlite3` is gitignored. Running `codeyam editor` detects this state (config.json exists, DB doesn't) and automatically runs `init --force` to rebuild the database and sync scenarios from the manifest.
+
+### Dev server not starting
+
+Check if another process holds the port:
+
+1. Look at `.codeyam/server-state.json` for the PID and port
+2. Kill any stale process
+3. Restart with `codeyam editor` (the editor command starts the server)
+
+### Step validation errors
+
+Each step has prerequisites. If a step refuses to run:
+
+1. Run `codeyam editor steps` to see which steps are complete
+2. Complete the prerequisite steps first
+3. Don't skip steps — the workflow is sequential
+
+### Dimension mismatch
+
+If previews look wrong or captures fail:
+
+- Check `screenSizes` in `.codeyam/config.json` for valid dimension names
+- Scenario `dimensions` must reference names defined in `screenSizes`
+- Preview commands must also include `dimension` — don't omit it
+
+### Preview not updating
+
+If changes aren't reflected in the preview:
+
+- The dev server may need to rebuild — check terminal output for compilation errors
+- Hard-refresh the preview: `codeyam editor preview '{"path":"<current-path>","dimension":"<dimension>","forceRefresh":true}'`
+- Check `codeyam editor client-errors` for runtime errors blocking render
+
+## Anti-Patterns
+
+**Don't loop audit/analyze-imports.** If audit fails, fix the underlying issues (missing scenarios, failing tests). Running audit repeatedly without fixing anything wastes time.
+
+**Don't use `prisma db push --force-reset`.** This drops all data. Instead, add `@default()` values for new required columns, or make them optional (`Int?`). Use `npm run db:push`.
+
+**Don't hardcode viewport dimensions.** Always reference named dimensions from `screenSizes` in config.json (e.g., `"Desktop"`). Don't use raw pixel values like `1440x900`.
+
+**Don't use bash heredocs for JSON.** Braces and quotes in heredocs trigger Claude Code security warnings. Use the **Write tool** to create `.codeyam/tmp/scenario.json`, then `codeyam editor register @.codeyam/tmp/scenario.json`.
+
+**Don't blanket-ignore `.codeyam` in `.gitignore`.** Only machine-local files are ignored with granular patterns. Shared files (`config.json`, `editor-scenarios/`, etc.) must be committable.
+
+**Don't register scenarios for unbuilt features.** If the component or page doesn't exist yet, the scenario will capture a blank page. Build the component first, then create scenarios for what it actually renders.

package/codeyam-cli/templates/design-systems/clean-dashboard-design-system.md

@@ -0,0 +1,255 @@
+# Clean Dashboard Design System
+
+> Minimal, information-dense UI. Subtle depth via soft shadows and thin borders. For any web or mobile app.
+
+## Philosophy
+
+High data clarity, minimal chrome. Neutral palette with restrained color accents. Soft shadows and thin borders create depth without visual weight. Professional, calm motion. Consistent 4px grid.
+
+**Rules:**
+
+1. Cards use `var(--bg-surface)` — never hardcoded or colored backgrounds
+2. Text hierarchy: primary → secondary → tertiary (never skip levels)
+3. No drop shadows on elements already inside a card
+4. Max 2 font weights per card
+5. Both light and dark mode required via `data-theme` attribute
+
+---
+
+## Colors
+
+### Light Mode
+
+```css
+[data-theme='light'] {
+  --bg-base: #f7f8fa; /* page background */
+  --bg-surface: #ffffff; /* cards, panels */
+  --bg-overlay: #ffffff; /* modals, dropdowns */
+  --bg-muted: #f2f3f7; /* hover states, inactive */
+  --bg-active: #eef2ff; /* selected items */
+
+  --text-primary: #1a1b25;
+  --text-secondary: #6b7280;
+  --text-tertiary: #9ca3af;
+  --text-disabled: #c4c7ce;
+
+  --border: #e8e9ed;
+  --border-strong: #d1d3db;
+
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.06), 0 1px 2px rgba(0, 0, 0, 0.04);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+```
+
+### Dark Mode
+
+```css
+[data-theme='dark'] {
+  --bg-base: #14141f;
+  --bg-surface: #1e1e2e;
+  --bg-overlay: #252537;
+  --bg-muted: #252537;
+  --bg-active: #2d2d45;
+
+  --text-primary: #e8e9f0;
+  --text-secondary: #9899aa;
+  --text-tertiary: #5e5f72;
+  --text-disabled: #3a3a50;
+
+  --border: #2a2a3e;
+  --border-strong: #383856;
+
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.3);
+  --shadow-md: 0 4px 12px rgba(0, 0, 0, 0.4);
+}
+```
+
+Respect `@media (prefers-color-scheme: dark)` on `:root:not([data-theme="light"])`.
+
+### Accents
+
+```css
+/* These don't change between modes */
+--green-a: #34d399;
+--green-b: #a7f3d0; /* positive states */
+--red: #f87171; /* negative states */
+--purple-a: #9b8afb;
+--purple-b: #c4b5fd;
+--blue-a: #60a5fa;
+--blue-b: #bae6fd;
+--yellow: #fcd34d;
+```
+
+### Semantic
+
+```css
+--success-bg: var(--green-b);
+--success-text: #065f46;
+--danger-bg: #fee2e2;
+--danger-text: #991b1b;
+--warning-bg: #fef9c3;
+--warning-text: #854d0e;
+```
+
+### Ordered Palette
+
+```css
+/* For any categorical sequence: tags, categories, avatars, etc. */
+--palette-1: #6c8ef5; /* blue-purple */
+--palette-2: #34d399; /* green */
+--palette-3: #f87171; /* red */
+--palette-4: #fbbf24; /* yellow */
+--palette-5: #a78bfa; /* purple */
+--palette-6: #22d3ee; /* cyan */
+```
+
+---
+
+## Typography
+
+**Font stack:** `'Inter', sans-serif`
+
+| Style   | Size | Weight  | Notes                 |
+| ------- | ---- | ------- | --------------------- |
+| Display | 48px | 600     | Large emphasis values |
+| 2XL     | 24px | 400/600 | Section headings      |
+| LG      | 18px | 400/600 | Card titles           |
+| SM      | 14px | 400/600 | Body, labels          |
+| XS      | 12px | 400/600 | Captions, timestamps  |
+
+---
+
+## Spacing & Radius
+
+Base unit: 4px. Scale: 4, 8, 12, 16, 20, 24, 32, 40px.
+
+| Context              | Value       |
+| -------------------- | ----------- |
+| Card padding         | `20px 24px` |
+| Gap between cards    | 16px        |
+| Gap between sections | 24px        |
+
+```css
+--radius-sm: 6px; /* badges, chips */
+--radius-md: 8px; /* inputs, small cards */
+--radius-lg: 12px; /* cards, panels */
+--radius-xl: 16px; /* large containers */
+--radius-full: 9999px; /* pills, avatars */
+```
+
+---
+
+## Layout
+
+### Common Patterns
+
+- **Sidebar:** 200px fixed, `--bg-surface`, right border
+- **Top bar:** 52px height, `--bg-surface`, bottom border. Contains: breadcrumbs (left), search (center), actions (right)
+- **Side panel:** 260px fixed, `--bg-surface`, left border (optional, toggle on small viewports)
+- **Main content:** flex-1, `--bg-base`, 24px padding
+
+### Navigation States
+
+- Section labels: XS, `--text-tertiary`, uppercase, `letter-spacing: 0.08em`
+- Nav items: SM, `--text-secondary`, hover → `--bg-muted`
+- Active item: `--bg-active`, `--text-primary`, weight 600
+- Nested indent: 16px
+
+### Mobile / Small Viewport
+
+- Sidebar collapses to hamburger menu or bottom tab bar
+- Side panel becomes slide-over or hidden
+- Cards stack single-column, full width, reduce padding to 16px
+- Top bar simplified: hamburger + key actions only
+
+---
+
+## Components
+
+### Card
+
+```css
+.card {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 20px 24px;
+  box-shadow: var(--shadow-sm);
+}
+```
+
+**Variants:** none — cards are always neutral surface color.
+
+**Interactive states:** hover → `--bg-muted` background or `--shadow-md`. No transform.
+
+### Value Card
+
+Card with: label (SM, `--text-secondary`), emphasized value (Display 48px, semibold), optional trend indicator. Positive: `--green-a` + `↗`. Negative: `--red` + `↘`. Trend text: XS, weight 500.
+
+### Button
+
+```css
+.btn {
+  padding: 0 14px;
+  border-radius: var(--radius-md);
+  font-weight: 500;
+  font-size: 13px;
+  border: none;
+  cursor: pointer;
+}
+/* Hover: 8% brightness shift. Disabled: 40% opacity, not-allowed. */
+```
+
+| Variant      | Background       | Text               | Border/Shadow                    |
+| ------------ | ---------------- | ------------------ | -------------------------------- |
+| Filled       | `--text-primary` | `--bg-base`        | none                             |
+| Filled muted | `--bg-muted`     | `--text-primary`   | none                             |
+| Outline      | transparent      | `--text-primary`   | `1px solid var(--border-strong)` |
+| Ghost        | transparent      | `--text-secondary` | none                             |
+
+| Size         | Padding     | Font Size |
+| ------------ | ----------- | --------- |
+| SM           | `6px 10px`  | 12px      |
+| MD (default) | `8px 14px`  | 13px      |
+| LG           | `11px 18px` | 14px      |
+
+Icon-only: square at size height. Split button: text + chevron with 1px divider.
+
+### Badge / Pill
+
+`border-radius: var(--radius-sm)` for chips, `--radius-full` for pills. Use accent colors at low opacity for backgrounds.
+
+### Input
+
+`--bg-surface`, `1px solid var(--border)`, `--radius-md`, SM text. Focus: `--border-strong` or accent ring.
+
+### Table / Data Row
+
+Rows 32px height, `border-bottom: var(--border)`. Labels SM, `--text-secondary`. Hover → `--bg-muted`.
+
+---
+
+## Motion
+
+```css
+--transition-fast: 100ms ease; /* hover states */
+--transition-base: 180ms ease; /* general transitions */
+--transition-slow: 280ms ease-in-out; /* panels, overlays */
+```
+
+Calm and professional — no bounce or spring. Subtle opacity and position transitions only.
+
+---
+
+## Checklist
+
+- [ ] Page bg is `--bg-base`, cards are `--bg-surface` — no hardcoded colors
+- [ ] Both `data-theme="light"` and `"dark"` fully supported
+- [ ] Text uses primary/secondary/tertiary hierarchy consistently
+- [ ] All spacing on 4px grid
+- [ ] No colored card backgrounds (except active-state chips)
+- [ ] No shadows on elements inside cards
+- [ ] Max 2 font weights per card
+- [ ] Motion is subtle and fast — no bounce effects
+- [ ] Icons are outlined, 1.5px stroke, inherit currentColor
+- [ ] Ordered palette colors used consistently for categorical items