@codeyam/codeyam-cli 0.1.0-staging.8aea589 → 0.1.0-staging.8b51541

package/codeyam-cli/templates/codeyam-setup-skill.md

@@ -1,468 +0,0 @@
----
-name: CodeYam Setup
-autoApprove: true
-description: |
-  Use this skill when the user asks to "setup CodeYam" or needs to configure CodeYam for their project.
-  This skill guides you through:
-  - Configuring the dev server start command
-  - Testing that the project starts correctly in isolation
-  - Creating universal mocks for dependencies that prevent startup
-  Use when: User runs `codeyam init` and wants to complete the setup process
----
-
-# CodeYam Setup Assistant
-
-## Quick Reference: Mock Path Decision Tree
-
-```
-Where is the error coming from?
-│
-├── node_modules package (e.g., @prisma/client, @supabase/supabase-js)
-│   └── Mock path: .codeyam/universal-mocks/node_modules/{package}.ts
-│       Example: .codeyam/universal-mocks/node_modules/@prisma/client.ts
-│
-└── Project file (e.g., lib/db.ts, packages/prisma/index.ts)
-    └── Mock path: .codeyam/universal-mocks/{same-path-as-original}
-        Example: .codeyam/universal-mocks/lib/db.ts
-        Example: .codeyam/universal-mocks/packages/prisma/index.ts
-```
-
-## Quick Reference: Mock Writing Rules
-
-**BEFORE writing any mock:**
-
-1. Read the original file first
-2. Note all its export names exactly
-
-**WHEN writing the mock:**
-
-1. Export names MUST match exactly (case-sensitive)
-2. ALL code MUST be inside exports (no helper variables outside)
-3. Keep it minimal - empty methods are fine
-
-**AFTER writing the mock:**
-
-```bash
-codeyam validate-mock .codeyam/universal-mocks/{path-to-your-mock}
-```
-
----
-
-## Setup Workflow
-
-### Step 1: Configure Webapp Start Command
-
-**ACTION 1:** Read configuration files:
-
-- `.codeyam/config.json` - get webapps array
-- Root `package.json` - find start scripts
-- Each webapp's `package.json` - find direct scripts
-
-**ACTION 2:** Identify start commands for each webapp:
-
-Look for scripts that start the dev server. Priority order:
-
-1. Root convenience scripts: `"dev": "cd apps/web && pnpm dev"`
-2. Webapp's own scripts: `"dev": "next dev"` or `"dev": "remix dev"`
-
-**ACTION 3:** Ask user which webapp(s) to configure:
-
-Use `AskUserQuestion` with `multiSelect: true` to let the user choose which webapp(s) to set up:
-
-```
-I found [N] webapp(s) in your project. Which would you like to configure for CodeYam?
-
-Options (select one or more):
-□ [Framework] at [path] - Start: `[command]`
-□ [Framework] at [path] - Start: `[command]`
-□ All webapps
-```
-
-**Note:** For projects with a single webapp, you may skip this and proceed directly. For multi-webapp projects, always ask.
-
-**ACTION 4:** Determine the correct start command with port
-
-The startCommand must include a `$PORT` placeholder that CodeYam will substitute at runtime.
-
-**IMPORTANT:** Commands always run from the **project root**, not the webapp directory. For webapps in subdirectories, you must ensure the command can run from root.
-
-**Option A: Root has a convenience script (recommended)**
-
-If the root `package.json` has a script that chains to the webapp:
-
-```json
-// Root package.json
-"scripts": {
-  "dev": "cd dashboard && pnpm dev"
-}
-```
-
-Then test from root:
-
-```bash
-# From project root - this should work
-pnpm dev --port 9999
-```
-
-**Option B: No root script - use shell command**
-
-If there's no root convenience script, use `sh -c` to change directory:
-
-```bash
-# Test this from project root
-sh -c "cd dashboard && pnpm dev --port 9999"
-```
-
-Config for this approach:
-
-```json
-"startCommand": {
-  "command": "sh",
-  "args": ["-c", "cd dashboard && pnpm dev --port $PORT"]
-}
-```
-
-**Option C: Using PORT env var**
-
-Some frameworks read from PORT environment variable:
-
-```bash
-PORT=9999 pnpm dev
-```
-
-**AVOID the `--` separator** - it often breaks with nested/chained commands like `cd dashboard && pnpm dev -- --port 9999`.
-
-**ACTION 5:** Update `.codeyam/config.json` with the working startCommand including `$PORT`:
-
-**For webapps at root OR with root convenience script:**
-
-```json
-"startCommand": {
-  "command": "pnpm",
-  "args": ["dev", "--port", "$PORT"]
-}
-```
-
-**For webapps in subdirectory without root script:**
-
-```json
-"startCommand": {
-  "command": "sh",
-  "args": ["-c", "cd <webapp-path> && pnpm dev --port $PORT"]
-}
-```
-
-**For env var approach:**
-
-```json
-"startCommand": {
-  "command": "pnpm",
-  "args": ["dev"],
-  "env": { "PORT": "$PORT" }
-}
-```
-
-**ACTION 6:** Sync to database:
-
-```bash
-codeyam update-config
-```
-
-### Step 2: Test Startup for Selected Webapps
-
-**IMPORTANT: You must test EVERY webapp selected in Step 1**
-
-**ACTION 1:** Get the selected webapps from config:
-
-```bash
-cat .codeyam/config.json | grep -A 100 '"webapps"'
-```
-
-Or read `.codeyam/config.json` directly and note all webapp paths.
-
-**ACTION 2:** Test each webapp individually using `--webappPath`:
-
-For a project with webapps at paths `apps/web` and `apps/admin`:
-
-```bash
-# Test first webapp
-codeyam test-startup --webappPath apps/web --debug
-
-# Test second webapp (only after first succeeds or is fixed)
-codeyam test-startup --webappPath apps/admin --debug
-```
-
-For a single webapp at root (path is `.`):
-
-```bash
-codeyam test-startup --webappPath . --debug
-```
-
-**ACTION 3:** Track progress for each webapp:
-
-- Keep a checklist of all webapps
-- Mark each as passing or failing
-- ALL selected webapps must pass before proceeding to Step 4
-
-**Flow for each webapp:**
-
-- If success → Move to next webapp
-- If error → Go to Step 3, create mocks, re-test THIS webapp until it passes
-- Only after ALL selected webapps pass → Go to Step 4
-
-### Step 3: Fix Errors (Environment Variables or Mocks)
-
-**Note:** Apply this step to whichever webapp(s) failed. Fixes apply to ALL webapps.
-
-**3A. Analyze the error**
-
-Read the error output from the failing webapp. Identify:
-
-- What is causing the error?
-- Is it a missing environment variable? → Use **3B (Environment Variables)**
-- Is it a database/API client initializing? → Use **3C (Mocks)**
-
-**3B. Add Environment Variables (if needed)**
-
-For errors about missing env vars (e.g., `NEXT_PUBLIC_API_URL is undefined`), add them to `.codeyam/config.json`:
-
-```json
-"environmentVariables": [
-  {
-    "key": "NEXT_PUBLIC_API_URL",
-    "value": "http://localhost:3000"
-  },
-  {
-    "key": "DATABASE_URL",
-    "value": "postgresql://mock:mock@localhost:5432/mock"
-  }
-]
-```
-
-Then sync and re-test:
-
-```bash
-codeyam update-config && codeyam test-startup --webappPath <path> --debug
-```
-
-**Note:** These are safe dummy values - they won't connect to real services.
-
-**3C. Determine if a mock is needed**
-
-For errors from code trying to connect to external services (databases, APIs), create mocks.
-
-Read the error output. Identify:
-
-- What file is throwing the error?
-- What dependency is it trying to use?
-
-**3D. Determine mock path**
-
-Use the decision tree above:
-
-- Error from `@prisma/client`? → `.codeyam/universal-mocks/node_modules/@prisma/client.ts`
-- Error from `lib/supabase.ts`? → `.codeyam/universal-mocks/lib/supabase.ts`
-- Error from `packages/prisma/index.ts`? → `.codeyam/universal-mocks/packages/prisma/index.ts`
-
-**3E. Read the original file**
-
-ALWAYS read the original file before creating a mock. Note:
-
-- What names are exported?
-- Are they `export const`, `export function`, `export default`?
-
-**3F. Write the mock**
-
-Create a minimal mock that:
-
-- Exports the SAME names as the original
-- Has ALL code inlined in exports
-- Returns simple values (null, [], {}, 0)
-
-**3G. Validate before retrying**
-
-```bash
-codeyam validate-mock .codeyam/universal-mocks/{path-to-mock}
-```
-
-Fix any errors shown, then re-test the specific webapp that failed:
-
-```bash
-codeyam test-startup --webappPath <failing-webapp-path> --debug
-```
-
-Repeat until the webapp passes, then continue testing remaining webapps.
-
-### Step 4: Success
-
-Once `test-startup` passes for ALL selected webapps:
-
-1. Run `codeyam suggest --limit 1 --verbose` (timeout: 5 minutes)
-2. Tell user CodeYam is ready
-3. Offer to simulate the suggested component
-
----
-
-## Mock Examples
-
-### Example: Prisma Client
-
-Original at `packages/prisma/index.ts`:
-
-```typescript
-export const prisma = new PrismaClient();
-export default prisma;
-```
-
-Mock at `.codeyam/universal-mocks/packages/prisma/index.ts`:
-
-```typescript
-export const prisma = {
-  $connect: async () => {},
-  $disconnect: async () => {},
-  $transaction: async (fn: any) => (typeof fn === 'function' ? fn(prisma) : []),
-  user: {
-    findFirst: async () => null,
-    findMany: async () => [],
-    create: async () => ({}),
-  },
-} as any;
-
-export default prisma;
-```
-
-### Example: Supabase Client
-
-Original at `lib/supabase.ts`:
-
-```typescript
-export const supabase = createClient(url, key);
-```
-
-Mock at `.codeyam/universal-mocks/lib/supabase.ts`:
-
-```typescript
-export const supabase = {
-  auth: {
-    getSession: async () => ({ data: { session: null }, error: null }),
-    onAuthStateChange: () => ({
-      data: { subscription: { unsubscribe: () => {} } },
-    }),
-  },
-  from: () => ({
-    select: () => ({ data: [], error: null }),
-    insert: () => ({ data: null, error: null }),
-  }),
-} as any;
-```
-
-### Example: Node Module Mock
-
-For `@clerk/nextjs`, create `.codeyam/universal-mocks/node_modules/@clerk/nextjs.ts`:
-
-```typescript
-export const auth = () => ({ userId: null, sessionId: null });
-export const currentUser = async () => null;
-export const ClerkProvider = ({ children }: any) => children;
-```
-
----
-
-## Troubleshooting
-
-### "Entity not found" / Duplicate exports
-
-**Symptom:** Warning about entity not found, then duplicate export error
-
-**Cause:** Mock export name doesn't match original file's export name
-
-**Fix:**
-
-1. Run `codeyam validate-mock .codeyam/universal-mocks/{path}`
-2. Check the "originalExports" in the output
-3. Rename your mock's export to match exactly
-
-### "Module has no exports"
-
-**Symptom:** Mock file appears empty or has no exports
-
-**Cause:** Non-exported helper variables were used
-
-**Fix:** Inline everything directly in exports:
-
-```typescript
-// ❌ BAD - helper gets dropped
-const mockMethods = { findFirst: async () => null };
-export const prisma = { user: mockMethods };
-
-// ✅ GOOD - all inline
-export const prisma = {
-  user: { findFirst: async () => null },
-} as any;
-```
-
-### "File not found" for mock
-
-**Symptom:** Mock path doesn't match any original file
-
-**Cause:** Wrong path in `.codeyam/universal-mocks/`
-
-**Fix:** Mock path must mirror original exactly:
-
-- Original: `packages/prisma/index.ts`
-- Mock: `.codeyam/universal-mocks/packages/prisma/index.ts`
-
-### Error persists after creating mock
-
-**Cause:** Different error, or mock didn't apply correctly
-
-**Fix:**
-
-1. Check `/tmp/codeyam/local-dev/{slug}/project/{file}` to see if mock was applied
-2. Run `codeyam validate-mock` to check for issues
-3. The error message may be from a different file - trace carefully
-
----
-
-## Key Principles
-
-1. **Mock at the source** - If `getConfig()` fails because `findProjectRoot()` returns null, mock `findProjectRoot`, not every function that calls it.
-
-2. **Read before write** - Always read the original file before creating a mock.
-
-3. **Validate before retry** - Use `codeyam validate-mock` to catch issues before running test-startup again.
-
-4. **Keep mocks minimal** - Empty methods and null returns are usually enough. The goal is to provide a simple mock with a structurally accurate return value. Do not import anything for mocks. Keep the mock simple.
-
-5. **Match exports exactly** - Export names are case-sensitive and must match the original.
-
----
-
-## Success Criteria
-
-Setup is complete when:
-
-- ✅ Selected `webapps` configured in `.codeyam/config.json` with startCommand **including `$PORT` placeholder**
-- ✅ `environmentVariables` added to config (if required for startup)
-- ✅ `codeyam test-startup --webappPath <path> --debug` passes for all SELECTED webapps
-- ✅ User knows how to use CodeYam (analyze, test)
-
-**CRITICAL:** The startCommand must include `$PORT` in the args (e.g., `["dev", "--port", "$PORT"]`) or env (e.g., `{"PORT": "$PORT"}`). Without this, CodeYam cannot start the server on the required port for capture.
-
-## Wrap It Up
-
-- Always end by presenting the user with a basic overview of CodeYam
-
-```
-CodeYam is set up!
-
-You can now:
-
-- Open the CodeYam dashboard: run `codeyam` or ask me to open it for you
-- Simulate any function or method in your project. Just ask me to `simulate [NAME OF FUNCTION OR METHOD]`
-- Ask me to test any function or method and I will be able to write tests more easily using the generated data structure CodeYam provides.
-
-To start how about simulating [FILE PATH AND ENTITY NAME OF SUGGESTED COMPONENT]?
-
-Do you want me to simulate that now?
-```

package/codeyam-cli/templates/codeyam-sim-skill.md

@@ -1,222 +0,0 @@
----
-name: CodeYam Simulation
-autoApprove: true
-description: |
-  Use this skill to create interactive simulations of components and functions using CodeYam's analysis.
-  Use when: User asks to simulate/analyze a component, generate scenarios, see visual output with screenshots,
-  or demonstrate code behavior. This skill runs full CodeYam analysis with scenario capture and visual results.
----
-
-# CodeYam Simulation Assistant
-
-Use this skill to help users create interactive simulations of their code using CodeYam's full analysis pipeline, including scenario generation, data capture, and screenshot visualization.
-
-## When to Use This Skill
-
-- User asks to "simulate" or "analyze" a component/function
-- User wants to see visual output with screenshots
-- User requests scenario generation
-- User wants to demonstrate code behavior interactively
-- User mentions viewing results in a browser
-- You want to show how code behaves with different data states
-
-## Important: Permissions Already Configured
-
-The `codeyam init` command has already auto-approved:
-
-- ✅ All CodeYam CLI commands (including `codeyam analyze`, `codeyam entities`, etc.)
-- ✅ All CodeYam skills
-- ✅ Read/Write operations for `.codeyam/ai-requests/` and `.codeyam/ai-responses/` directories
-- ✅ All file operations in the `.codeyam/` directory
-
-You can freely use Read, Write, and Bash tools for CodeYam operations without asking for permission.
-
-## AI Mode: Automatic Detection
-
-CodeYam automatically detects the best AI mode based on your configuration:
-
-### Mode Detection (Automatic)
-
-CodeYam checks in this priority order:
-
-1. **Direct API Mode**: If an API key is found → uses Anthropic API directly
-   - Project: `.codeyam/secrets.json` (highest priority)
-   - Home: `~/.codeyam/secrets.json` (shared across projects)
-   - Environment variables
-2. **Claude CLI Mode**: If no API key AND `.claude` folder exists → uses Claude Code CLI
-3. **Error**: If neither is found → provides helpful error message
-
-### Claude CLI Mode (Default for Claude Code Users)
-
-- **What it is**: CodeYam calls `claude -p` (headless Claude Code) for all AI requests
-- **Authentication**: Uses your existing Claude authentication automatically
-- **When used**: Automatically when using CodeYam from Claude Code (`.claude` folder detected)
-- **How it works**:
-  1. Run `codeyam analyze --entity ComponentName 'path/to/file.tsx'`
-  2. When analyzer needs AI (key attributes, scenarios, data), it executes: `claude -p "prompt" --output-format json`
-  3. Claude CLI returns response
-  4. Analyzer continues automatically until complete
-- **User experience**: Fast, fully autonomous, zero setup, zero API keys
-
-### Direct API Mode
-
-- **What it is**: CodeYam calls Anthropic API directly for AI requests
-- **When used**: Automatically when an API key is found in:
-  - `~/.codeyam/secrets.json` (recommended - shared across projects)
-  - `.codeyam/secrets.json` (project-specific override)
-  - Environment variables
-- **Setup**: Add your API key to `~/.codeyam/secrets.json`:
-  ```json
-  {
-    "ANTHROPIC_API_KEY": "sk-ant-..."
-  }
-  ```
-- **Benefits**: Faster, can run in background without Claude Code
-
-### No Manual Mode Selection Required!
-
-**Mode is detected automatically** - you never need to specify which mode to use:
-
-- ✅ No `--claude-cli` flag needed
-- ✅ Works seamlessly in Claude Code (`.claude` folder detected)
-- ✅ API keys take precedence if configured
-- ✅ Clear error if neither mode is available
-
-## ⚠️ CRITICAL: User Interruption Protocol
-
-**If the user interrupts with "[Request interrupted by user]":**
-
-- ❌ **STOP ALL PROCESSING IMMEDIATELY** - Do not continue processing AI requests
-- ❌ Do not read any more AI request files
-- ❌ Do not write any more AI response files
-- ❌ Do not poll BashOutput anymore
-- ✅ Wait for user instructions
-- ✅ **ONLY resume processing if the user explicitly asks you to continue**
-- ✅ If resuming, check for any unprocessed requests and continue from where you stopped
-
-**Why this matters**: The user may be debugging, updating code, or needs to stop the process. Continuing to process requests after interruption can cause confusion and wastes tokens.
-
-## Workflow: Simulating a Component
-
-When a user asks to simulate a component (e.g., "simulate BranchIndicator"), **ALWAYS follow this complete workflow**:
-
-### Step 1: Search for the Entity
-
-**IMPORTANT**: Never skip this step! Even if you think you know where the entity is, always search first to get the exact entity name and file path.
-
-Use the `codeyam entities` command to find matching entities:
-
-```bash
-codeyam entities ComponentName
-```
-
-This will return all entities matching that name with their file paths.
-
-### Step 2: Handle Results
-
-**If SINGLE match found:**
-
-- Automatically proceed to Step 3 with that entity
-- No need to ask the user which one
-
-**If MULTIPLE matches found:**
-
-- Present the list to the user
-- Ask which file path they want to simulate
-- Example: "I found 3 entities named 'Button'. Which one would you like to simulate?"
-  - Button in components/ui/Button.tsx
-  - Button in legacy/Button.tsx
-  - Button in admin/Button.tsx
-
-**If NO matches found:**
-
-- Inform the user the entity wasn't found
-- Suggest they check the entity name or file path
-
-### Step 3: Run Analysis
-
-Once you have the specific entity and file path, run the analysis. CodeYam automatically detects whether to use Claude CLI or direct API mode:
-
-**ACTION 1:** Ensure the CodeYam server is running:
-
-```bash
-codeyam start
-```
-
-This will start the server if it's not already running. If it's already running, it will just confirm that.
-
-**ACTION 2:** Run the analysis in the background:
-
-```bash
-codeyam analyze --entity ComponentName 'path/to/file.tsx'
-```
-
-**Optional: Provide Business Logic Context**
-
-If you just made changes to business logic that require specific data to demonstrate, use the `--context` and `--scenario-count` flags:
-
-```bash
-codeyam analyze --entity ComponentName 'path/to/file.tsx' \
-  --context "Added warning icon that displays when status is 'deleted'. Create a scenario with status='deleted' to show the warning icon prominently" \
-  --scenario-count 3
-```
-
-**When to provide context:**
-
-- ✅ New feature that depends on specific data values (e.g., "show badge when count > 0")
-- ✅ Conditional rendering added based on data (e.g., "warning icon when status is 'deleted'")
-- ✅ Business logic changed in a way that specific data reveals the change (e.g., "empty state when array is empty")
-- ❌ Pure refactoring (extracting components, renaming, reorganizing) - no context needed
-- ❌ Style-only changes (colors, fonts, spacing) - no context needed
-- ❌ Type safety improvements - no context needed
-
-**Context format:**
-
-1. Describe what changed (the new behavior)
-2. Describe what data needs to be present/missing/specific to demonstrate it
-3. Be specific about data values that trigger the behavior
-
-**Good examples:**
-
-- "Added notification badge that appears when unreadCount > 0. Create a scenario with unreadCount=5 to show the badge"
-- "Updated empty state to show when items array is empty. Create a scenario with an empty array to demonstrate the empty state"
-- "Added warning icon for deleted files. Create a scenario with status='deleted' to show the warning icon"
-
-**Bad examples:**
-
-- ❌ "New filtering feature: when 'showErrors' prop is true, only display files with errors" (describes the logic, not what data to provide)
-- ❌ "Refactored to use union types" (no business logic change)
-- ❌ "Updated colors to match design system" (style-only)
-
-**Instructions:**
-
-1. Run the command with `run_in_background: true` and `timeout: 600000` (10 minutes)
-2. Extract the entity SHA from the `codeyam entities` output (Step 1) - it's the first column in the results
-3. Tell user: "I've started the CodeYam analysis. Depending on the complexity of the analysis it might take between 1 and 5 minutes. Then your browser will open automatically with the results."
-4. Provide the progress link: "You can watch the real-time analysis progress at: http://localhost:3111/entity/{entitySha}"
-5. **That's it! Do nothing else.** Don't poll output, don't monitor progress, don't check status.
-
-The analysis runs autonomously using `claude -p` (headless Claude Code) and opens the browser when complete.
-
-**What happens**:
-
-1. Background process analyzes the entity and generates data scenarios
-2. Background process launches the project server and captures the results
-3. Browser automatically opens with results
-
-The browser will show:
-
-- All generated scenarios
-- Screenshots for each scenario (for visual components)
-- Data structures and mock data
-- Any errors encountered
-
-## When NOT to Use This Skill
-
-- User wants to write unit/integration tests → Use **CodeYam Testing** skill instead
-- User asks for Jest mocks or test templates → Use **CodeYam Testing** skill instead
-- User wants to run `codeyam generate-data-structure` → Use **CodeYam Testing** skill instead
-
----
-
-**Remember**: CodeYam analyzes your code to discover real data scenarios and usage patterns. The analysis runs autonomously and provides comprehensive visual documentation of component behavior.