|
| 1 | +# CLI Debugging with File-Based Logging |
| 2 | + |
| 3 | +When debugging the CLI, `console.log` will break the TUI (Terminal User Interface). Use file-based logging to capture debug output without interfering with the application's display. |
| 4 | + |
| 5 | +## File-Based Logging Strategy |
| 6 | + |
| 7 | +1. **Write logs to a temporary file instead of console**: |
| 8 | + |
| 9 | + - Create a log file at a known location, e.g., `/tmp/roo-cli-debug.log` |
| 10 | + - Use `fs.appendFileSync()` to write timestamped log entries |
| 11 | + - Example logging utility: |
| 12 | + |
| 13 | + ```typescript |
| 14 | + import fs from "fs" |
| 15 | + const DEBUG_LOG = "/tmp/roo-cli-debug.log" |
| 16 | + |
| 17 | + function debugLog(message: string, data?: unknown) { |
| 18 | + const timestamp = new Date().toISOString() |
| 19 | + const entry = data |
| 20 | + ? `[${timestamp}] ${message}: ${JSON.stringify(data, null, 2)}\n` |
| 21 | + : `[${timestamp}] ${message}\n` |
| 22 | + fs.appendFileSync(DEBUG_LOG, entry) |
| 23 | + } |
| 24 | + ``` |
| 25 | + |
| 26 | +2. **Clear the log file before each debugging session**: |
| 27 | + - Run `echo "" > /tmp/roo-cli-debug.log` or use `fs.writeFileSync(DEBUG_LOG, "")` at app startup during debugging |
| 28 | + |
| 29 | +## Iterative Debugging Workflow |
| 30 | + |
| 31 | +Follow this feedback loop to systematically narrow down issues: |
| 32 | + |
| 33 | +1. **Add targeted logging** at suspected problem areas based on your hypotheses |
| 34 | +2. **Instruct the user** to reproduce the issue using the CLI normally |
| 35 | +3. **Read the log file** after the user completes testing: |
| 36 | + - Run `cat /tmp/roo-cli-debug.log` to retrieve the captured output |
| 37 | +4. **Analyze the log output** to gather clues about: |
| 38 | + - Execution flow and timing |
| 39 | + - Variable values at key points |
| 40 | + - Which code paths were taken |
| 41 | + - Error conditions or unexpected states |
| 42 | +5. **Refine your logging** based on findings—add more detail where needed, remove noise |
| 43 | +6. **Ask the user to test again** with updated logging |
| 44 | +7. **Repeat** until the root cause is identified |
| 45 | + |
| 46 | +## Best Practices |
| 47 | + |
| 48 | +- Log entry/exit points of functions under investigation |
| 49 | +- Include relevant variable values and state information |
| 50 | +- Use descriptive prefixes to categorize logs: `[STATE]`, `[EVENT]`, `[ERROR]`, `[FLOW]` |
| 51 | +- Log both the "happy path" and error handling branches |
| 52 | +- When dealing with async operations, log before and after `await` statements |
| 53 | +- For user interactions, log the received input and the resulting action |
| 54 | + |
| 55 | +## Example Debug Session |
| 56 | + |
| 57 | +```typescript |
| 58 | +// Add logging to investigate a picker selection issue |
| 59 | +debugLog("[FLOW] PickerSelect onSelect called", { selectedIndex, item }) |
| 60 | +debugLog("[STATE] Current selection state", { currentValue, isOpen }) |
| 61 | +
|
| 62 | +// After async operation |
| 63 | +const result = await fetchOptions() |
| 64 | +debugLog("[FLOW] fetchOptions completed", { resultCount: result.length }) |
| 65 | +``` |
| 66 | + |
| 67 | +Then ask: "Please reproduce the issue by [specific steps]. When you're done, let me know and I'll analyze the debug logs." |
0 commit comments