@codeyam/codeyam-cli 0.1.0-staging.da5baf5 → 0.1.0-staging.dbc742d

package/codeyam-cli/templates/skills/codeyam-sim/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: codeyam-sim
+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.

package/codeyam-cli/templates/skills/codeyam-test/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: codeyam-test
+autoApprove: true
+description: |
+  Use this skill to write comprehensive unit and integration tests using CodeYam's mock generation.
+  Use when: User asks to write tests, generate mocks, understand function dependencies, or improve test coverage.
+  This skill uses the `codeyam generate-data-structure` command to create realistic test mocks based on actual code analysis.
+---
+
+# CodeYam Testing Assistant
+
+Use this skill to help users write comprehensive unit and integration tests for their code using CodeYam's dependency analysis and mock generation.
+
+## When to Use This Skill
+
+- User asks to write unit or integration tests
+- User wants to generate Jest mocks for a function
+- User needs help understanding function dependencies for testing
+- User requests mock data for testing
+- You see an opportunity to improve test coverage
+- Testing complex functions with many dependencies
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam generate-data-structure`)
+- ✅ All CodeYam skills
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use Read, Write, and Bash tools for CodeYam operations without asking for permission.
+
+## Workflow: Writing Tests with CodeYam
+
+### Step 1: Generate Mock Template
+
+Use `codeyam generate-data-structure` to analyze the function and generate a mock template:
+
+```bash
+codeyam generate-data-structure --entity FunctionName path/to/file.ts
+```
+
+**What this does:**
+
+1. Runs partial analysis (data structure only, no scenarios)
+2. Discovers all function dependencies
+3. Generates Jest mock template with proper types
+4. Caches results for instant subsequent runs
+
+**Optional flags:**
+
+- `--json` - Output raw data structure for advanced use cases
+- `--output path/to/output.ts` - Write to file instead of stdout
+
+**Example:**
+
+```bash
+codeyam generate-data-structure --entity computeBranchEntityDiff codeyam-cli/src/webserver/app/lib/branchEntityComparison.ts
+```
+
+### Step 2: Understand the Analysis Output
+
+The mock template shows:
+
+- **Dependencies by module** - All external functions/imports
+- **Mock declarations** - `jest.mock()` calls for each module
+- **Return value templates** - Sample data for `mockReturnValue()`
+
+**With `--json` flag, you get:**
+
+```json
+{
+  "dataForMocks": {
+    "getProjectRoot()": "/project/root",
+    "getBranchDiffForProject(baseBranch, compareBranch)": [...]
+  },
+  "dependencySchemas": {
+    "module/path": {
+      "functionName": { "type": "object", "properties": {...} }
+    }
+  }
+}
+```
+
+### Step 3: Write the Test
+
+Use the generated template as a starting point:
+
+**Key principles learned from experience:**
+
+1. **Mock external dependencies only** - Let internal functions run
+2. **Use realistic mock data** - Based on CodeYam's analysis
+3. **Test behavior, not implementation** - Focus on what the function does
+4. **Consider edge cases** - Added files, deleted files, empty results, etc.
+
+**Example pattern:**
+
+```typescript
+// Mock external dependencies
+jest.mock('path/to/module', () => ({
+  externalFunction: jest.fn(),
+}));
+
+describe('FunctionName', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Setup default mocks
+  });
+
+  it('should handle normal case', () => {
+    // Arrange: Setup mocks
+    // Act: Call function
+    // Assert: Verify behavior
+  });
+
+  it('should handle edge case', () => {
+    // Test edge cases
+  });
+});
+```
+
+### Step 4: Run the Test
+
+```bash
+npx jest path/to/test.test.ts --verbose
+```
+
+### Step 5: Iterate
+
+If tests fail:
+
+1. Check mock data matches actual usage
+2. Verify mock call counts (added files call extract once, modified call twice)
+3. Ensure edge cases are handled
+4. Use `jest.clearAllMocks()` between tests for isolation
+
+## Common Testing Patterns
+
+### Integration Tests
+
+- Mock external dependencies (fs, child_process, imports)
+- Let internal logic run naturally
+- Test complete workflows
+
+### Unit Tests
+
+- Mock all dependencies
+- Test single function in isolation
+- Focus on edge cases and error handling
+
+### Cache Testing
+
+- Test both cache hit and miss scenarios
+- Verify cache writes happen correctly
+- Ensure cache reads prevent unnecessary work
+
+## Tips from Experience
+
+1. **Call counts matter** - Different file statuses call dependencies differently:
+   - Modified files: extract entities from old AND new content (2 calls)
+   - Added files: extract only from new content (1 call)
+   - Deleted files: extract only from old content (1 call)
+
+2. **Mock isolation** - Use `jest.clearAllMocks()` between tests to prevent interference
+
+3. **Realistic data** - Use CodeYam's analysis to ensure mock data matches real usage patterns
+
+4. **Test structure** - Organize by scenarios (cache hit, cache miss, edge cases)
+
+## When NOT to Use This Skill
+
+- User wants to simulate a component in the browser → Use **CodeYam Simulation** skill instead
+- User wants to see visual screenshots of scenarios → Use **CodeYam Simulation** skill instead
+- User asks to "analyze" or "simulate" an entity → Use **CodeYam Simulation** skill instead
+
+---
+
+**Remember**: This skill is for writing traditional unit/integration tests with Jest. For running CodeYam simulations with screenshots and scenarios, use the CodeYam Simulation skill.

package/codeyam-cli/templates/skills/codeyam-verify/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: codeyam-verify
+autoApprove: true
+description: |
+  Use this skill after making code changes that impact application functionality.
+  Automatically run simulations to verify your changes and present results to the user.
+  Use when: You've completed making changes to visual components or library functions and are ready to present your work.
+
+  NOTE: A Stop hook is installed that will remind you to use this skill if you made changes to .ts/.tsx/.jsx/.vue files during the session.
+---
+
+# CodeYam Verify Assistant
+
+Use this skill to automatically verify code changes by running simulations and presenting results to the user.
+
+## When to Use This Skill
+
+**IMPORTANT: Use this skill automatically after making code changes that affect:**
+
+- Visual components (React components, Vue components, UI elements)
+- Library functions (exported functions, utility methods, business logic)
+- Any other code that impacts application functionality
+
+**You should invoke this skill:**
+
+- After completing a set of code changes
+- Before presenting your work to the user
+- When you want to demonstrate the impact of your changes
+
+**DO NOT use this skill for:**
+
+- Documentation-only changes
+- Type definition changes that don't affect runtime behavior
+- Configuration file updates (unless they affect component behavior)
+
+## Important: Permissions Already Configured
+
+The `codeyam init` command has already auto-approved:
+
+- ✅ All CodeYam CLI commands (including `codeyam verify`)
+- ✅ All CodeYam skills
+- ✅ All file operations in the `.codeyam/` directory
+
+You can freely use the verify command without asking for permission.
+
+## Workflow: Verifying Your Changes
+
+When you're ready to present your changes to the user, follow this workflow:
+
+### Step 1: Run the Verify Command
+
+Execute the verify command to detect changed entities and launch the dashboard:
+
+```bash
+codeyam verify
+```
+
+**Optional: Provide Business Logic Context**
+
+If you made business logic changes that require specific data to demonstrate, use the `--context` and `--scenario-count` flags:
+
+```bash
+codeyam verify \
+  --context "Added warning icon that displays when status is 'deleted'. Create scenarios 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
+
+**What this does:**
+
+1. Scans your git working directory for changed files
+2. Detects which entities (functions, components) were modified or added
+3. Filters to only visual and library entities
+4. Starts the CodeYam dashboard server (if not already running)
+5. Opens your browser to the Git verification page
+6. **If context provided**: Passes it to the analyzer to generate scenarios demonstrating the changes
+
+### Step 2: Interpret the Results
+
+The verify command will either:
+
+**If NO visual or library entities changed:**
+
+- The command exits with a message
+- No further action needed
+- Present your changes to the user normally
+
+**If entities WERE changed:**
+
+- The command lists all changed entities
+- Opens the browser to http://localhost:3111/git
+- The dashboard shows your changes with options to analyze them
+
+### Step 3: Present Results to the User
+
+After running `codeyam verify`, tell the user:
+
+**Example message:**
+
+```
+I've completed the changes and kicked off simulations for the modified components.
+
+Changed entities:
+  • Button (visual) - components/Button.tsx
+  • formatDate (library) - utils/formatters.ts
+
+You can view the results and run simulations at: http://localhost:3111/git
+
+On the Git page, you can:
+  • View all changed entities
+  • Click "Analyze All" to run simulations for all entities
+  • Click "Analyze" on individual entities to run specific simulations
+  • View real-time progress as analyses complete
+```
+
+## Complete Example
+
+**User asks:** "Can you update the Button component to support a loading state?"
+
+**Your workflow:**
+
+1. Make the code changes to the Button component
+2. BEFORE presenting to the user, invoke this skill
+3. Run `codeyam verify` with context to demonstrate the new loading state
+4. Present the changes to the user with the verification link
+
+**Your response:**
+
+```
+I've updated the Button component to support a loading state. The changes include:
+- Added a `loading` prop to the Button interface
+- Display a spinner when loading is true
+- Disable the button during loading
+
+I've kicked off simulations to verify these changes with scenarios that show the loading state:
+
+codeyam verify \
+  --context "Added loading state to Button. Create scenarios with loading=true to show the spinner and disabled state" \
+  --scenario-count 2
+
+You can view the results at: http://localhost:3111/git
+
+The simulations will show:
+- Normal button state
+- Loading button state with spinner
+```
+
+## Important Notes
+
+- **Always run verify AFTER making changes** - not before, not during
+- **The verify command only detects uncommitted changes** - changes that aren't yet committed to git
+- **If no relevant entities changed** - the command will exit quickly and you can present your work normally
+- **Simulations run in the background** - they may take 1-5 minutes to complete
+- **Multiple entities can be analyzed at once** - use the "Analyze All" button on the Git page
+
+## Integration with Your Workflow
+
+Make this automatic part of your workflow:
+
+1. User asks for code changes
+2. You make the changes
+3. **[NEW STEP]** You run `codeyam verify` to verify the changes
+4. You present the changes to the user with the verification link
+
+This ensures the user can always see simulation results for your changes, building trust and providing visual confirmation that the changes work as expected.

package/package.json

@@ -1,61 +1,72 @@
 {
   "name": "@codeyam/codeyam-cli",
-  "version": "0.1.0-staging.da5baf5",
+  "version": "0.1.0-staging.dbc742d",
   "description": "Local development CLI for CodeYam analysis",
   "type": "module",
   "bin": {
     "codeyam": "./codeyam-cli/src/codeyam-cli.js"
   },
   "scripts": {
-    "postinstall": "node ./scripts/finalize-analyzer.cjs"
+    "postinstall": "node ./scripts/npm-post-install.cjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-code": "^2.0.22",
-    "@anthropic-ai/sdk": "^0.71.0",
-    "@aws-sdk/client-dynamodb": "^3.899.0",
-    "@aws-sdk/util-dynamodb": "^3.902.0",
-    "@modelcontextprotocol/sdk": "^1.24.0",
-    "@octokit/auth-app": "^8.1.0",
+    "@anthropic-ai/claude-code": "^2.1.7",
+    "@anthropic-ai/sdk": "^0.78.0",
+    "@aws-sdk/client-dynamodb": "^3.990.0",
+    "@aws-sdk/s3-request-presigner": "^3.990.0",
+    "@aws-sdk/util-dynamodb": "^3.990.0",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@octokit/auth-app": "^8.2.0",
     "@octokit/request": "^10.0.3",
     "@octokit/rest": "^22.0.0",
-    "@react-router/express": "^7.10.1",
-    "@react-router/node": "^7.10.1",
-    "react-router": "^7.10.1",
+    "@react-router/express": "^7.13.0",
+    "@react-router/node": "^7.13.1",
+    "react-router": "^7.13.0",
     "@sendgrid/mail": "^8.1.4",
-    "@supabase/supabase-js": "2.52.1",
-    "better-sqlite3": "^12.4.1",
+    "@supabase/supabase-js": "2.88.0",
+    "better-sqlite3": "^12.6.2",
     "chalk": "^5.6.2",
     "chokidar": "^4.0.3",
-    "cli-spinners": "^3.3.0",
+    "cli-spinners": "^3.4.0",
     "domhandler": "^5.0.3",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",
     "fetch-retry": "^6.0.0",
     "get-port": "^7.1.0",
-    "htmlparser2": "^10.0.0",
+    "htmlparser2": "^10.1.0",
     "isbot": "^4",
-    "jsdom": "^26.1.0",
+    "jsdom": "^27.4.0",
     "json5": "^2.2.3",
     "jsonc-parser": "^3.2.1",
-    "kysely": "^0.28.5",
-    "lru-cache": "^11.2.4",
+    "kysely": "^0.28.11",
+    "lru-cache": "^11.2.5",
     "lucide-react": "^0.556.0",
-    "openai": "^6.9.0",
-    "p-queue": "^8.1.0",
-    "p-retry": "^6.2.1",
-    "pg": "^8.16.3",
+    "minimatch": "^10.2.3",
+    "openai": "^6.16.0",
+    "p-queue": "^9.1.0",
+    "p-retry": "^7.1.1",
+    "pg": "^8.19.0",
     "piscina": "^5.1.4",
     "pixelmatch": "^5.3.0",
-    "playwright": "^1.56.1",
+    "playwright": "1.58.0",
     "pluralize": "^8.0.0",
     "prompts": "^2.4.2",
-    "react": "~18.2.0",
-    "react-diff-viewer-continued": "^3.4.0",
-    "react-dom": "~18.2.0",
+    "react": "^19.2.3",
+    "react-diff-viewer-continued": "4.0.6",
+    "react-dom": "^19.2.3",
+    "react-markdown": "^10.1.0",
     "react-resizable": "^3.0.5",
-    "react-syntax-highlighter": "^15.5.13",
+    "react-syntax-highlighter": "^15.6.1",
+    "remark-gfm": "^4.0.1",
+    "node-pty": "^1.0.0",
     "sharp": "^0.34.5",
-    "simple-git": "^3.28.0",
+    "ws": "^8.18.3",
+    "@xterm/xterm": "^6.0.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-web-links": "^0.11.0",
+    "@xterm/addon-webgl": "^0.18.0",
+    "@xterm/addon-canvas": "^0.7.0",
+    "simple-git": "^3.32.2",
     "typescript": "^5.9.3",
     "uuid": "^11.1.0",
     "yargs": "^18.0.0",