@codeyam/codeyam-cli 0.1.0-staging.8e7b1bd → 0.1.0-staging.b8a55ba

package/codeyam-cli/templates/debug-command.md

@@ -1,141 +0,0 @@
-# Debug Scenario or Analysis
-
-When a user asks to debug a scenario or analysis (e.g., `/debug [ID]`), use this systematic process. The `codeyam debug` command auto-detects whether you've provided a scenario ID or analysis ID.
-
-## CRITICAL: What You Can and Cannot Modify
-
-**NEVER modify the client's original source code.** The client code in `/tmp/codeyam/local-dev/{slug}/project` is a checkout of the user's repository. We do not fix bugs in their code.
-
-**You can ONLY modify CodeYam-generated files**, which are identifiable by:
-
-- Files with `// This file is auto-generated by CodeYam` at the top
-- Files with scenario suffixes like `_No_Branches_No_Changes.ts`
-- Mock data files in `__codeyamMocks__/` directories
-- Scenario route files like `static.codeyam-ai-codeyam.*.tsx`
-
-**If the error is in client code**, the bug is in how CodeYam generates mocks or rewrites imports - fix the generation logic in the CodeYam repo, not the client code.
-
-## Step 1: Run Debug Command
-
-**IMPORTANT**: The scenario/analysis ID is assumed to belong to the **current project** (the repo you are working in). Run the debug command from the current project directory:
-
-```bash
-codeyam debug ID
-```
-
-The command auto-detects whether the ID is a scenario or analysis.
-
-The output includes:
-
-1. **Project path**: `/tmp/codeyam/local-dev/{slug}/project`
-2. **Start command**: The exact `cd ... && pnpm dev` command to run
-3. **URL**: `http://localhost:3112/static/codeyam-sample`
-4. **Log path**: Where to watch for errors
-
-As a note for when needed: all of the data for the analysis comes from the `.codeyam/db.sqlite3` database
-
----
-
-## Step 2: Manual Debugging in /tmp
-
-Work directly in the Tmp Project at `/tmp/codeyam/local-dev/{slug}/project`.
-
-### 2.1 Start the development server
-
-Copy the start command from the debug output and run it:
-
-```bash
-cd /tmp/codeyam/local-dev/{slug}/project && pnpm dev
-# Or the framework-specific command shown in the debug output
-```
-
-### 2.2 Verify the page loads with curl
-
-**CRITICAL: Server starting is NOT sufficient verification.**
-
-```bash
-curl -s http://localhost:3112/static/codeyam-sample | head -50
-```
-
-**What to look for:**
-
-- **Success**: HTML with `<div>` elements, no error messages
-- **Failure**: Look for `"statusCode":500` or `"err":` in the JSON
-
-### 2.3 Verification checklist
-
-Before declaring "it works", confirm ALL of these:
-
-- [ ] Server process started without crashing
-- [ ] `curl` returns clean HTML (no `statusCode:500` or error messages)
-- [ ] Browser shows the component rendering (not blank/error)
-- [ ] No errors in browser console (DevTools > Console)
-
-**If ANY of these fail, the bug is NOT fixed. Keep iterating.**
-
-### 2.4 Identify and fix the issue
-
-Common failure points:
-
-1. **Server fails to start**: JSON parse errors, missing dependencies, port in use
-2. **Page fails to compile**: Missing exports in mock files, import resolution failures
-3. **Page loads but component doesn't render**: ReferenceError, missing mock data
-
-**Fix ONLY CodeYam-generated files in the Tmp Project.** Look for files with `// This file is auto-generated by CodeYam` headers. If the error points to client code, the root cause is in CodeYam's generation logic - you'll fix that in the CodeYam repo, not here.
-
-Iterate until all verification checks pass.
-
----
-
-## Step 3: Document the Fix
-
-Once verified (all checklist items pass):
-
-1. **What file(s) did you edit?**
-2. **What was the change?**
-3. **Why was the original code wrong?**
-
-Categorize the fix:
-
-- **Mock content issue**: The generated mock had wrong exports or missing values
-- **Scenario file issue**: The scenario component file had incorrect structure
-- **Import rewriting issue**: An import was incorrectly rewritten or not rewritten
-- **Package.json corruption**: JSON files were incorrectly modified
-- **Missing dependency**: A required package wasn't installed
-
----
-
-## Step 4: Create a Failing Test (in CodeYam Repo)
-
-Write a test that fails without the fix:
-
-| Bug type                 | Test location                                                                      |
-| ------------------------ | ---------------------------------------------------------------------------------- |
-| Scenario file generation | `background/src/lib/virtualized/project/__tests__/writeScenarioComponents.test.ts` |
-| Universal mocks          | `background/src/lib/virtualized/project/__tests__/writeUniversalMocks.test.ts`     |
-| Mock generation          | `background/src/lib/virtualized/project/__tests__/constructMockCode.test.ts`       |
-| Entity analysis          | `packages/analyze/src/lib/files/__tests__/*.test.ts`                               |
-| Scope analysis           | `packages/ai/src/lib/astScopes/__tests__/*.test.ts`                                |
-
----
-
-## Step 5: Implement the Fix
-
-1. Edit the source file in the CodeYam Repo
-2. Run the test to confirm it passes
-3. Rebuild the CLI: `pnpm cli`
-4. Clear the cached project: `rm -rf /tmp/codeyam/local-dev/{slug}/project`
-5. Re-run debug: `codeyam debug ID`
-6. **Run the full verification checklist** - server starts, page loads, component renders
-
----
-
-## Key Source Files
-
-| Purpose               | File                                                                |
-| --------------------- | ------------------------------------------------------------------- |
-| Universal mocks       | `background/src/lib/virtualized/project/writeUniversalMocks.ts`     |
-| Scenario file writing | `background/src/lib/virtualized/project/writeScenarioComponents.ts` |
-| Mock code generation  | `background/src/lib/virtualized/project/constructMockCode.ts`       |
-| Entity analysis       | `packages/analyze/src/lib/files/analyzeEntity.ts`                   |
-| Data structure        | `packages/ai/src/lib/generateEntityDataStructure.ts`                |