# Issue #57: Command Output Capture — Implementation Plan

## Overview

Engineers run commands during troubleshooting sessions but the output is lost — exports say "ran this command" but not what it returned. This feature adds a "Paste Output" textarea on action nodes and custom action steps so command output is captured in session data and included in all exports and session review.

**Scope:** Built-in action nodes AND custom action steps.
**Migration:** None required — `decisions` is already a JSONB array with flexible dict entries.

---

## Public Interfaces / Type Changes

- **Backend:** Add `command_output: Optional[str] = Field(None, max_length=10000)` to `DecisionRecord` in `session.py`
- **Frontend:** Add `command_output?: string | null` to `DecisionRecord` type in `session.ts`
- **API:** No endpoint changes — `PUT /api/v1/sessions/{id}` continues to accept full decisions array; now includes optional `command_output`
- **Validation:** Backend enforces 10,000 character hard limit (returns 422 on overflow); frontend shows live character count

---

## Files to Modify

### Backend (3 files)

| File | Change |
|------|--------|
| `backend/app/schemas/session.py` | Add `command_output` field to `DecisionRecord` |
| `backend/app/services/export_service.py` | Render `command_output` in all 4 export formats with command context |
| `backend/app/core/session_to_tree.py` | Include command output when converting session decisions to forked tree nodes |

### Frontend (3 files)

| File | Change |
|------|--------|
| `frontend/src/types/session.ts` | Add `command_output` to `DecisionRecord` type |
| `frontend/src/pages/TreeNavigationPage.tsx` | Add capture UI for both built-in action nodes and custom action steps |
| `frontend/src/pages/SessionDetailPage.tsx` | Render `command_output` in decision review and clipboard copy |

---

## Implementation Steps

### Step 1: Backend Schema

**File:** `backend/app/schemas/session.py`

- Add `command_output: Optional[str] = Field(None, max_length=10000)` to `DecisionRecord`
- The `max_length=10000` provides backend validation — requests exceeding this return 422

### Step 2: Frontend Type

**File:** `frontend/src/types/session.ts`

- Add `command_output?: string | null` to the `DecisionRecord` type
- This ensures the field is not dropped by TypeScript typing during round-trips

### Step 3: TreeNavigationPage — Capture UI for Built-in Action Nodes

**File:** `frontend/src/pages/TreeNavigationPage.tsx`

**State:**
- Add `const [commandOutput, setCommandOutput] = useState('')` (same pattern as existing `notes` state)
- Clear `commandOutput` when node changes (same place `notes` is cleared)
- When revisiting a step, preload existing `command_output` from the decision record if present

**UI — on action nodes with `currentNode.commands?.length > 0`:**
- Render a collapsible "Paste Output (Optional)" section below the commands display
- Inside: a textarea with:
  - Placeholder: `"Paste command output here..."`
  - Monospace font (`font-mono`), consistent with command code block styling
  - `bg-white/10` background styling to match existing design
  - Live character count display: `"{count} / 10,000"` shown below the textarea
  - Max length enforced on the frontend at 10,000 characters
- Use a `Terminal` icon from `lucide-react` for the section label

**Persistence — in `handleContinue()`:**
- Add `command_output: commandOutput.trim() || null` to the decision record pushed to the session
- Empty or whitespace-only input is normalized to `null` (treated as not provided)

### Step 4: TreeNavigationPage — Capture UI for Custom Action Steps

**File:** `frontend/src/pages/TreeNavigationPage.tsx`

Custom action steps create their decision record at insertion time, which is different from built-in action nodes. The output capture UI and behavior should be the same as Step 3, but persistence requires updating the existing decision rather than creating a new one.

**UI:**
- Same collapsible "Paste Output (Optional)" section as built-in action nodes
- Available when a custom action step has commands defined

**Persistence:**
- Before `handleContinueToDescendant` or `handleCustomBranchComplete` is called, update the current custom step's decision record with `command_output: commandOutput.trim() || null`
- Persist the updated decisions array to the backend before navigation/completion transitions
- This is a wrapper flow around the existing custom step logic — not a replacement of it

### Step 5: Export Service — All 4 Formats

**File:** `backend/app/services/export_service.py`

**Helpers to add:**
- A helper to safely extract and normalize `command_output` from a decision dict (strip whitespace, return `None` if empty)
- A helper to resolve the commands associated with a step for context display:
  1. First look up the tree snapshot action node by `node_id`
  2. Fallback to custom step metadata by `node_id`
  3. Fallback to no command list (just show the output)

**Export rendering per format** (all guarded by `if command_output := decision.get("command_output")`):

**Markdown (`_generate_markdown_export`):**
```
**Commands Run:** `ping 8.8.8.8`, `tracert 8.8.8.8`
**Output:**
```
{output}
```
```

**Text (`_generate_text_export`):**
```
  Commands Run: ping 8.8.8.8, tracert 8.8.8.8
  Output:
    {output with each line indented}
```

**HTML (`_generate_html_export`):**
```html
<p><strong>Commands Run:</strong> <code>ping 8.8.8.8</code>, <code>tracert 8.8.8.8</code></p>
<pre><code>{html.escape(output)}</code></pre>
```

**PSA (`_generate_psa_export`):**
```
Commands: ping 8.8.8.8, tracert 8.8.8.8
Output:
  {output with each line indented}
```

### Step 6: SessionDetailPage — Review Display

**File:** `frontend/src/pages/SessionDetailPage.tsx`

**Decision review:**
- After the `action_performed` rendering for each decision, check for `command_output`
- If present, render in a `<pre>` block with monospace styling and preserved whitespace
- Label: "Command Output" with consistent styling

**Clipboard copy (`copyTicketNotes`):**
- After the action performed line, add:
  ```
  Output:
  {decision.command_output}
  ```
- Only include if `command_output` is present and non-empty

### Step 7: Session-to-Tree Conversion

**File:** `backend/app/core/session_to_tree.py`

- When building node descriptions from decisions, check for `command_output`
- If present, append the output text to the node description so forked trees retain the captured output
- Format: include a "Command Output:" label followed by the output text

---

## Edge Cases & Failure Modes

| Scenario | Behavior |
|----------|----------|
| Existing sessions without `command_output` | Render normally with no errors — field is optional |
| Output exceeds 10,000 characters | Frontend prevents input beyond limit; backend returns 422 if somehow exceeded |
| Empty or whitespace-only input | Normalized to `null` — treated as not provided |
| Multiline output, JSON, special characters | Preserved as-is; HTML export escapes all content |
| Steps without commands | Output can still be stored; export shows output even without command context |
| Multi-command action nodes | One shared output field per step (not per command) |
| Revisiting a completed step | Preloads the previously captured output |

---

## Test Cases

### Backend API Tests (`test_sessions.py`)

1. Update a session with `command_output` in a decision record → verify it round-trips correctly on GET
2. Submit `command_output` exceeding 10,000 characters → verify 422 response
3. Submit empty string and whitespace-only `command_output` → verify stored as `null`

### Export Tests

4. Markdown export includes command context and fenced code block for output
5. Text export includes output block with preserved line breaks
6. HTML export includes escaped `<pre><code>` block
7. PSA export includes compact command context and indented output
8. Multi-command action node exports with single shared output block
9. Export of session without any `command_output` renders cleanly (no errors, no empty blocks)

### Custom Action Step Tests

10. Insert custom action step with commands → capture output → continue → verify output stored in decision
11. Custom step output appears in all export formats

### Frontend Behavior Tests

12. Action node with commands shows the "Paste Output" section (collapsed by default)
13. Custom action step with commands shows the "Paste Output" section
14. Action node WITHOUT commands does NOT show the "Paste Output" section
15. Character count updates live as user types
16. Revisiting a step preloads previously captured output
17. Session detail page renders output block with monospace formatting
18. "Copy to clipboard" includes command output when present

---

## Verification Checklist (Manual)

1. `cd frontend && npm run build` — confirm no TypeScript errors
2. Start a session on a tree with action nodes that have commands:
   - Paste output into the textarea
   - Click Continue
   - Verify output persists in the session data
3. Start a session and add a custom action step with commands:
   - Paste output
   - Continue to next step
   - Verify output persists
4. Complete a session → check SessionDetailPage shows the command output with proper formatting
5. Export in all 4 formats → verify output appears correctly formatted in each
6. Use "Copy to clipboard" on a step with output → verify output is included
7. Run a session on a tree WITHOUT commands on action nodes → verify no output section appears
8. Test with existing sessions that have no `command_output` → verify they render and export without errors
9. Test pasting large output (near 10,000 chars) → verify character count and limit work
10. Test pasting multiline output with special characters → verify preservation in review and exports

---

## Assumptions

- One shared output field per step, not per individual command
- Maximum stored output is 10,000 characters
- v1 does not include syntax highlighting or image paste
- No feature flag gating — ships directly
- Collapsed-by-default UI keeps the interface clean for steps where output isn't needed
