@codeyam/codeyam-cli 0.1.0-staging.596f0eb → 0.1.0-staging.76566f9

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

@@ -1,303 +0,0 @@
-# Debug Scenario or Analysis
-
-When a user asks to debug a scenario or analysis (e.g., `/debug [ID]`), use this systematic process.
-
-## 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 (with `// This file is auto-generated by CodeYam` header)
-- Mock data files in `__codeyamMocks__/` directories
-- Data in the local SQLite database (to fix incorrect analysis data)
-- Universal mocks in `.codeyam/config.json`
-
----
-
-## Part 1: Debugging for All Projects
-
-### Step 1: Run Debug Command
-
-```bash
-codeyam debug ID
-```
-
-The command auto-detects whether the ID is a scenario or analysis. Output includes:
-
-1. **Project path**: `/tmp/codeyam/local-dev/{slug}/project`
-2. **Start command**: The exact command to run the dev server
-3. **URL**: Where to access the scenario
-4. **Log path**: Where to watch for errors
-
----
-
-### Step 2: Identify the Error Type
-
-Read the log file or error output to categorize the issue:
-
-| Error Type          | Symptoms                                         | Solution Path                          |
-| ------------------- | ------------------------------------------------ | -------------------------------------- |
-| **Runtime error**   | `TypeError`, `ReferenceError`, component crashes | Check mock data, may need database fix |
-| **Missing mock**    | `Cannot read property of undefined`              | Add universal mock                     |
-| **Wrong mock type** | `X is not a function` or `Cannot call X`         | Fix data in database                   |
-| **Import error**    | `Cannot find module`                             | Check universal mocks or entity name   |
-
----
-
-### Step 3: Database Debugging (Fix Analysis Data)
-
-Sometimes the analysis engine generates incorrect data. You can fix it directly in the database.
-
-#### Database Location
-
-The database is in the **project's `.codeyam/` directory**, not in `/tmp`:
-
-```
-{project-root}/.codeyam/db.sqlite3
-```
-
-For example: `/Users/you/myproject/.codeyam/db.sqlite3`
-
-#### Key Tables
-
-| Table       | Purpose             | Key Columns                              |
-| ----------- | ------------------- | ---------------------------------------- |
-| `entities`  | Detected entities   | `sha`, `name`, `file_path`, `metadata`   |
-| `analyses`  | Analysis results    | `id`, `entity_sha`, `status`, `metadata` |
-| `scenarios` | Generated scenarios | `id`, `analysis_id`, `name`, `metadata`  |
-
-#### Useful Queries
-
-**Find entity by name:**
-
-```bash
-sqlite3 .codeyam/db.sqlite3 \
-  "SELECT sha, name, file_path FROM entities WHERE name LIKE '%EntityName%'"
-```
-
-**Find analysis for entity:**
-
-```bash
-sqlite3 .codeyam/db.sqlite3 \
-  "SELECT id, status FROM analyses WHERE entity_sha = 'ENTITY_SHA'"
-```
-
-**View scenario mock data:**
-
-```bash
-sqlite3 .codeyam/db.sqlite3 \
-  "SELECT name, json_extract(metadata, '$.data.mockData') FROM scenarios WHERE analysis_id = 'ANALYSIS_ID'" | python3 -m json.tool
-```
-
-**List all keys in mockData:**
-
-```bash
-sqlite3 .codeyam/db.sqlite3 \
-  "SELECT json_each.key FROM scenarios, json_each(json_extract(metadata, '$.data.mockData')) WHERE id = 'SCENARIO_ID'"
-```
-
-#### Common Data Issues
-
-**1. Wrong mock type (function vs object)**
-
-The generated mock may treat a function as an object or vice versa. Check the generated scenario file in `/tmp/codeyam/local-dev/{slug}/project/` to see how the mock is structured. Compare it to how the code actually uses the value.
-
-**2. Malformed keys in mockData**
-
-Sometimes keys contain full function call expressions (with arguments) instead of simple identifiers. This causes a mismatch between how mockData is stored and how the mock code accesses it.
-
-```bash
-# View all keys - look for ones with complex parentheses and arguments
-sqlite3 .codeyam/db.sqlite3 \
-  "SELECT json_each.key FROM scenarios, json_each(json_extract(metadata, '$.data.mockData')) WHERE id = 'SCENARIO_ID'"
-```
-
-Example of problematic key:
-
-```
-"useQuery(undefined, { enabled: isSignedIn })"
-```
-
-The mock code may look for `["useQuery"]` or `["useQuery()"]` but the data is at `["useQuery(undefined, {...})"]`.
-
-**3. Missing mock data for a dependency**
-
-If a property access chain isn't mocked, the mock data may be missing or keyed incorrectly.
-
-#### Fixing Data
-
-**Update mockData in a scenario:**
-
-```bash
-# Get current metadata
-sqlite3 .codeyam/db.sqlite3 "SELECT metadata FROM scenarios WHERE id = 'SCENARIO_ID'"
-
-# Update a specific key in mockData (use json_set for simple changes)
-sqlite3 .codeyam/db.sqlite3 \
-  "UPDATE scenarios SET metadata = json_set(metadata, '\$.data.mockData.\"correctedKey\"', json('{\"fixed\": \"value\"}')) WHERE id = 'SCENARIO_ID'"
-```
-
-**For complex mockData fixes**, it's often easier to:
-
-1. Export the metadata to a file
-2. Edit the JSON manually
-3. Update the database with the corrected JSON
-
-```bash
-# Export to file
-sqlite3 .codeyam/db.sqlite3 "SELECT metadata FROM scenarios WHERE id = 'SCENARIO_ID'" > /tmp/metadata.json
-
-# Edit /tmp/metadata.json with your fixes
-
-# Update (be careful with escaping)
-sqlite3 .codeyam/db.sqlite3 "UPDATE scenarios SET metadata = readfile('/tmp/metadata.json') WHERE id = 'SCENARIO_ID'"
-```
-
-**After fixing the database, regenerate scenario files by re-running analysis:**
-
-```bash
-codeyam analyze --entity EntityName path/to/file.tsx
-```
-
-Or, if you only need to regenerate the scenario files from existing data, you may be able to trigger a recapture from the CodeYam dashboard.
-
----
-
-### Step 4: Universal Mocks (Infrastructure Dependencies)
-
-For errors caused by infrastructure code that doesn't work in simulation (database clients, filesystem, etc.), add universal mocks.
-
-#### When to Use Universal Mocks
-
-Only use for functions that:
-
-1. Are called by MANY entities across ALL scenarios
-2. Don't work in simulation (need real database, filesystem, etc.)
-3. Return simple, scenario-independent values
-
-#### Adding a Universal Mock
-
-Edit `.codeyam/config.json`:
-
-```json
-{
-  "universalMocks": [
-    {
-      "entityName": "getProjectRoot",
-      "filePath": "lib/state.ts",
-      "content": "export function getProjectRoot() { return '/mock/project/root'; }"
-    }
-  ]
-}
-```
-
-Then rebuild: `pnpm build` (or your build command)
-
----
-
-### Step 5: Verify the Fix
-
-After making changes:
-
-1. **Restart the dev server** in `/tmp/codeyam/local-dev/{slug}/project`
-2. **Curl the URL** to check for errors:
-   ```bash
-   curl -s http://localhost:3112/static/... | head -50
-   ```
-3. **Check browser console** for runtime errors
-
-**Verification checklist:**
-
-- [ ] Server starts without crashing
-- [ ] `curl` returns HTML (no `statusCode:500`)
-- [ ] Component renders in browser
-- [ ] No console errors
-
----
-
-### Step 6: Report the Bug
-
-After fixing the data locally, document the issue so CodeYam can fix the underlying bug.
-
-**Create a bug report with:**
-
-1. What the incorrect data looked like (copy the relevant JSON)
-2. What it should have been
-3. How you fixed it (the SQL command or manual edit)
-4. Any patterns you noticed (e.g., "happens with property access chains")
-5. The entity name and file path
-
-**For CodeYam project:** Create an issue or note in the codebase describing the bug.
-
-**For client projects:** Share the bug report with the CodeYam team so they can fix the analysis engine.
-
----
-
-## Part 2: CodeYam Engine Debugging
-
-**This section is only relevant when working on the CodeYam project itself.**
-
-If you're debugging a client project, you can stop at Part 1. Report the bug and move on.
-
-### Identifying Engine Bugs
-
-When the error is in how CodeYam generates data or mocks (not in client code), you need to fix the engine.
-
-Signs of an engine bug:
-
-- Same pattern fails across multiple projects
-- Mock data structure doesn't match code patterns
-- Generated mock code has wrong syntax
-
-### Key Source Files
-
-| Purpose                  | File                                                                |
-| ------------------------ | ------------------------------------------------------------------- |
-| Scenario file generation | `background/src/lib/virtualized/project/writeScenarioComponents.ts` |
-| Mock code construction   | `packages/analyze/src/lib/files/analyze/constructMockCode.ts`       |
-| Data structure merging   | `background/src/lib/analyze/mergeDataStructure.ts`                  |
-| Entity analysis          | `packages/analyze/src/lib/files/analyzeEntity.ts`                   |
-
-### Debugging Workflow
-
-**1. Write a failing test first**
-
-| Bug type            | Test location                                                                      |
-| ------------------- | ---------------------------------------------------------------------------------- |
-| Scenario generation | `background/src/lib/virtualized/project/__tests__/writeScenarioComponents.test.ts` |
-| Mock generation     | `packages/analyze/src/lib/files/analyze/__tests__/constructMockCode.test.ts`       |
-| Entity analysis     | `packages/analyze/src/lib/files/__tests__/*.test.ts`                               |
-
-**2. Add debug logging to trace the issue**
-
-```typescript
-console.log('=== DEBUG ===');
-console.log('input:', JSON.stringify(input, null, 2));
-console.log('output:', result);
-```
-
-**3. Run tests**
-
-```bash
-pnpm test:unit -- --grep "relevant test pattern"
-```
-
-**4. Implement the fix**
-
-Fix the source file, ensure tests pass, then:
-
-```bash
-pnpm cli                                    # Rebuild CLI
-rm -rf /tmp/codeyam/local-dev/{slug}/project  # Clear cache
-codeyam debug ID                            # Re-test
-```
-
-### Common Bug Patterns
-
-| Pattern                      | Symptom                     | Likely Location                                   |
-| ---------------------------- | --------------------------- | ------------------------------------------------- |
-| Object vs function confusion | `X is not a function`       | `constructMockCode.ts` - entityType handling      |
-| Variable-qualified keys      | Wrong variable name in mock | `writeScenarioComponents.ts` - key parsing        |
-| Schema inference             | Wrong mock structure        | `mergeDataStructure.ts`                           |
-| Property chain issues        | Nested property undefined   | `constructMockCode.ts` - nested object generation |