@codeyam/codeyam-cli 0.1.0-staging.bbe4da9 → 0.1.0-staging.c9dc00c

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

@@ -1,453 +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
-  - Creating a sandbox to iterate on startup fixes directly
-  - Writing universal mocks for dependencies that prevent startup
-  - Verifying with test-startup at the end
-  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`:
-
-**IMPORTANT: Valid framework values are:** `Remix`, `Next`, `NextPages`, `CRA`, `Unknown`
-
-React Router 7 apps should use `"framework": "Remix"` (React Router 7 is the successor to Remix and uses the same
-architecture).
-
-**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: Setup Sandbox and Fix Startup Errors
-
-After configuring startCommands, create a sandbox to iterate on fixes directly.
-
-**2A. Tell the user what's happening**
-
-Before running `setup-sandbox`, inform the user:
-
-```
-Now I need to test that your app can start without real environment variables and
-no access to external services such as the database.
-
-I'll clone your project to a temporary directory and try running the dev server.
-Any code that fails due to missing env vars or external dependencies will need
-to be mocked. This may take a few iterations.
-```
-
-**2B. Create the sandbox**
-
-```bash
-codeyam setup-sandbox
-```
-
-This:
-
-- Copies the project to `/tmp/codeyam/local-dev/{slug}/project`
-- Sanitizes env files (replaces real values with dummies)
-- Applies any existing universal mocks
-- Shows start commands for each webapp
-
-**2C. Start a server in the sandbox**
-
-Use one of the start commands shown by setup-sandbox. Run in background:
-
-```bash
-cd /tmp/codeyam/local-dev/{slug}/project && pnpm dev --port 9999 &
-```
-
-**2D. Test the page**
-
-```bash
-curl http://localhost:9999
-```
-
-Or use WebFetch to see the response and any errors.
-
-**2E. Fix ALL errors in the sandbox first**
-
-**IMPORTANT:** Fix all errors directly in the sandbox before writing anything to `.codeyam/universal-mocks/`. This is more efficient than re-running `setup-sandbox` after each fix.
-
-**Iteration loop (stay in sandbox):**
-
-1. **Read the error** to identify the failing file (look for file paths in stack traces)
-2. **Read the file** in the sandbox: `/tmp/codeyam/local-dev/{slug}/project/{path}`
-3. **Edit the file** in the sandbox to fix the error with minimal mock code
-4. **Restart the server**: `pkill -f "next dev\|remix dev\|vite" ; cd /tmp/codeyam/local-dev/{slug}/project && <start-command> &`
-5. **Test again** with curl/fetch
-6. **Repeat steps 1-5** for each new error until the page loads successfully
-
-**Once the page loads successfully in the sandbox:**
-
-7. **Write ALL fixes** to `.codeyam/universal-mocks/{path}` in the original project
-8. **Validate each mock**: `codeyam validate-mock .codeyam/universal-mocks/{path}`
-9. **Re-run setup-sandbox** to verify mocks apply correctly: `codeyam setup-sandbox`
-10. **Start server and test** one more time to confirm
-
-**Key principles for fixes:**
-
-- Only modify CODE files (.ts, .tsx, .js, .jsx), never config files
-- Mock at the source (the function that fails, not its callers)
-- Keep fixes minimal - replace functions/methods with simple return values
-- Match the expected return type (null, [], {}, etc.)
-- Track which files you modified in the sandbox so you can write them all to universal-mocks at the end
-
-**2F. 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"
-  }
-]
-```
-
-Then run `codeyam update-config` to sync. These are safe dummy values.
-
-### Step 3: Final Verification
-
-Once all webapps work in the sandbox AND fixes have been written to `.codeyam/universal-mocks/`:
-
-**Test each webapp with test-startup:**
-
-```bash
-codeyam test-startup --webappPath <path> --debug
-```
-
-This verifies the mocks work correctly in the standard CodeYam flow.
-
-**ALL webapps must pass test-startup before proceeding to Step 4.**
-
-### Step 4: Success
-
-Once `test-startup` passes for ALL 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:
-
-- ✅ `webapps` configured in `.codeyam/config.json` with startCommand **including `$PORT` placeholder**
-- ✅ Sandbox created and all webapps start successfully with fixes applied
-- ✅ All fixes written to `.codeyam/universal-mocks/`
-- ✅ `codeyam test-startup --webappPath <path> --debug` passes for ALL 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.