Integrate fx as primary JSON/JSONL viewer in ksd dashboard

[durapensa]

Overview

Integrate fx (terminal JSON viewer) as the primary viewer for JSON/JSONL files in ksd, with clean screen takeover and return workflow.

Viewer Selection

Primary viewer: fx - https://fx.wtf/

• Native JSONL/streaming support for event logs
• Efficient handling of large files (4GB+)
• JavaScript expression support
• Single Go binary, easy to install

Installation: Users will need to install fx separately via their package manager or download from releases.

Keyboard Shortcut Workflow

Main ksd screen shortcuts:

• [V] - View mode (opens context-appropriate file in fx)
• [E] - View event log (knowledge/events.jsonl)
• [A] - View approved findings (knowledge/derived/approved.jsonl)
• [R] - View rejected findings (knowledge/derived/rejected.jsonl)
• [Q] - View analysis queue (knowledge/.background/analysis_queue.json)

View mode behavior:

1. User presses view shortcut (e.g., [V])
2. ksd saves terminal state
3. fx launches in full-screen mode with appropriate file
4. User explores data using fx's interactive features
5. User exits fx (q or Ctrl-C)
6. Control returns to ksd with screen restored

Context-aware viewing:

When pressing [V] from different screens:

• From main dashboard: Show menu of viewable files
• From triggers screen: View trigger state files
• From review screen: View current finding being reviewed
• From process monitor: View process logs

Implementation Notes

# Example integration in ksd
view_file() {
    local file="$1"
    tput smcup  # Save terminal state
    fx "$file" 2>/dev/null || {
        echo "Error: fx not found. Install from https://fx.wtf/"
        read -n1 -r -p "Press any key to continue..."
    }
    tput rmcup  # Restore terminal
}

Future Considerations

• Add configuration for alternative viewers (jqp, jless)
• Support for piping filtered output back to ksd
• Quick preview mode without full screen takeover
• Integration with search/filter results

Dependencies

• Requires fx to be installed and in PATH
• Falls back with helpful error message if not found
• Document installation in README