@codeyam/codeyam-cli 0.1.0-staging.483fdc2 → 0.1.0-staging.50df560

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

@@ -0,0 +1,149 @@
+# CodeYam Editor Project
+
+This project is being built with CodeYam's Code + Data Editor. The core principle is **code and data are developed together** — every component should have scenario data that drives what it renders.
+
+## Architecture: Components + Scenarios
+
+### Component Structure
+
+Build with a clear component hierarchy so individual components can be previewed in isolation:
+
+```
+app/
+  components/
+    Dashboard.tsx        ← page-level component
+    TaskList.tsx         ← displays a list, gets data from API or props
+    TaskCard.tsx         ← single item, pure props
+    EmptyState.tsx       ← shown when no data
+```
+
+Each component should accept props that let it be rendered independently. Avoid components that can only work when deeply embedded — they should be previewable on their own with mock data.
+
+### Scenarios
+
+A **scenario** is a named set of data that drives how the app renders. Scenarios exist at two levels:
+
+- **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"
+
+**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
+# 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:
+
+- Each scenario can seed the database with different data
+- API routes naturally return different results per scenario
+- This is closer to real-world behavior than prop mocking alone
+
+### Zooming In and Out
+
+The CodeYam Editor supports zooming between the full app view and isolated component views:
+
+- **Zoomed out**: See the whole app running with scenario data flowing through the database and APIs
+- **Zoomed in**: See a single component rendered in isolation with specific props
+
+Build components so they work at both zoom levels. A `TaskCard` should render correctly whether it's inside the full app or previewed alone with mock props.
+
+## Workflow
+
+1. Build a component
+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
+
+## Key Conventions
+
+- Component files go in `app/components/` (or `src/components/`)
+- One component per file, default export
+- 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/codeyam-editor-reference.md

@@ -0,0 +1,214 @@
+# .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`                 | Build the import dependency graph from source 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
+```
+
+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/codeyam-memory-hook.sh

@@ -3,7 +3,7 @@
 # Ensures rules are reviewed when associated code changes
 #
 # This hook checks that rules with matching `paths` patterns have been reviewed
-# (indicated by an updated `timestamp` field) when associated code files are modified.
+# (indicated by an updated lastAuditedAt in .claude/codeyam-rule-state.json) when associated code files are modified.
 
 set -e
 
@@ -21,9 +21,9 @@ if [ -z "$STAGED_FILES" ]; then
   exit 0
 fi
 
-# Function to convert ISO 8601 timestamp to epoch seconds
+# Function to convert ISO 8601 date string to epoch seconds
 # Handles both macOS and Linux date commands
-timestamp_to_epoch() {
+iso_to_epoch() {
   local ts="$1"
   # Remove trailing Z if present
   ts="${ts%Z}"
@@ -84,15 +84,14 @@ matches_pattern() {
   echo "$file" | grep -qE "$regex_pattern" 2>/dev/null
 }
 
-# Parse timestamp from YAML frontmatter
-get_rule_timestamp() {
+# Read lastAuditedAt from .claude/codeyam-rule-state.json
+RULE_STATE_FILE=".claude/codeyam-rule-state.json"
+get_rule_last_audited_at() {
   local rule_file="$1"
-  # Extract content between first two --- lines, then find timestamp
-  sed -n '1,/^---$/!{/^---$/q;p}' "$rule_file" 2>/dev/null | \
-    grep -E '^timestamp:' | \
-    sed 's/timestamp:[[:space:]]*//' | \
-    tr -d "'" | tr -d '"' | \
-    head -1
+  # Extract relative path from .claude/rules/
+  local rule_name="${rule_file#.claude/rules/}"
+  if [ ! -f "$RULE_STATE_FILE" ]; then echo ""; return; fi
+  node -e "try{const d=JSON.parse(require('fs').readFileSync('$RULE_STATE_FILE','utf-8'));console.log((d.rules&&d.rules['$rule_name']&&d.rules['$rule_name'].lastAuditedAt)||'')}catch{console.log('')}"
 }
 
 # Parse paths from YAML frontmatter
@@ -118,14 +117,14 @@ while IFS= read -r rule_file; do
   fi
   CHECKED_RULES="$CHECKED_RULES $rule_file"
 
-  rule_timestamp=$(get_rule_timestamp "$rule_file")
+  rule_last_audited=$(get_rule_last_audited_at "$rule_file")
 
-  # Skip rules without timestamp
-  if [ -z "$rule_timestamp" ]; then
+  # Skip rules without lastAuditedAt
+  if [ -z "$rule_last_audited" ]; then
     continue
   fi
 
-  rule_epoch=$(timestamp_to_epoch "$rule_timestamp")
+  rule_epoch=$(iso_to_epoch "$rule_last_audited")
 
   if [ "$rule_epoch" = "0" ]; then
     continue
@@ -156,7 +155,7 @@ while IFS= read -r rule_file; do
         # Get file modification time
         file_epoch=$(get_file_mtime "$staged_file")
 
-        # If file is newer than rule timestamp, flag it
+        # If file is newer than rule's lastAuditedAt, flag it
         if [ "$file_epoch" -gt "$rule_epoch" ]; then
           rule_is_outdated=true
           matched_file="$staged_file"
@@ -180,14 +179,14 @@ if [ -n "$OUTDATED_RULES" ]; then
   echo "  Claude Rules (Codeyam Memory): Outdated Documentation Detected"
   echo "================================================================"
   echo ""
-  echo "  The following rules have timestamps older than the code"
-  echo "  files they cover:"
+  echo "  The following rules were last audited before recent code"
+  echo "  changes to the files they cover:"
   echo "$OUTDATED_RULES"
   echo ""
   echo "  To proceed:"
   echo "    1. Review each rule to ensure it's still accurate"
-  echo "    2. Update the 'timestamp' field in the YAML frontmatter"
-  echo "    3. Stage the updated rule file(s)"
+  echo "    2. Run 'codeyam memory touch' to mark them as audited"
+  echo "    3. Stage the updated .claude/codeyam-rule-state.json"
   echo "    4. Commit again"
   echo ""
   echo "  Or ask Claude to \"run \`codeyam memory status\` and follow the instructions.\""