prole/docs/ncurses-installer.md

# Ncurses Installer Interface

## Overview

The Knoe Database Installer now supports a command-line, ncurses-based interface as an alternative to the GUI. This allows installation on headless systems, remote servers via SSH, or any environment where a graphical interface is unavailable or undesirable.

## Usage

### From Source

To run the installer with the ncurses interface:

```bash
./install.py --no-gui
```

To run the traditional GUI interface:

```bash
./install.py --gui
```

To run with auto-detection (uses GUI if display available, otherwise ncurses):

```bash
./install.py
```

### From Built Binary

```bash
# Auto-detect (default)
./dist/Knoe\ Installer.app/Contents/MacOS/knoe-installer

# Force ncurses mode
./dist/Knoe\ Installer.app/Contents/MacOS/knoe-installer --no-gui

# Force GUI mode
./dist/Knoe\ Installer.app/Contents/MacOS/knoe-installer --gui

# Or double-click the .app in Finder for GUI
```

## Features

### Same Screen Flow
The ncurses interface maintains the exact same screen order and operations as the GUI:

1. **Welcome** - Introduction and overview
2. **Dependencies Summary** - View all dependencies
3. **Network Scan** - Network configuration and scanning
4. **Environment Setup** - Configure KNOE_HOME and environment variables
5. **Kerberos Configuration** - Set up Kerberos authentication
6. **Database Creation** - Initialize database namespace and credentials
7. **Build Container** - Docker image build process
8. **Initialize Cluster** - PostgreSQL cluster setup
9. **Initialization Scripts** - Run database init scripts
10. **Deploy CNPG** - CloudNativePG deployment
11. **Create Installer** - Generate installation media

### Navigation

The ncurses interface supports multiple navigation methods:

**Keyboard Shortcuts:**
- `↑/↓` or `k/j` - Navigate between screens
- `←/→` or `h/l` - Move between footer buttons
- `Enter` - Activate selected button
- `n` - Next screen
- `p` - Previous screen
- `q` or `Q` - Quit installer

**Visual Layout:**
- **Header** - Shows installer title and status messages
- **Sidebar** - Navigation menu showing all screens (left)
- **Content Area** - Main screen content (right)
- **Footer** - Action buttons (Previous, Next, Quit)

### Architecture

The ncurses implementation shares the same business logic (`KnoeController`) as the GUI, ensuring consistent behavior across both interfaces.

**Key Components:**

1. **knoe/ncurses_ui.py** - UI primitives
   - `CursesWindow` - Basic window wrapper with rendering helpers
   - `TerminalConsole` - Scrollable console output
   - `NavFooter` - Navigation button bar
   - `InputField` - Text input widget
   - `Checkbox` - Checkbox widget

2. **knoe/ncurses_installer.py** - Main installer class
   - `KnoeNcursesInstaller` - Screen management and rendering
   - `run_ncurses_installer()` - Entry point for ncurses mode

3. **install.py** - Modified to support `--no-gui` argument
   - Parses command-line arguments
   - Routes to either Tk GUI or ncurses interface
   - Both modes use shared `KnoeController`

## Development

### Adding New Screens

To add a new screen to the ncurses interface:

1. Register the screen in `_register_screens()`:
```python
self.pages.append(("new_screen_id", self._render_new_screen))
```

2. Implement the render method:
```python
def _render_new_screen(self):
    win = CursesWindow(self.main_content_win)
    win.render_title("New Screen Title", y=2)
    win.render_paragraph("Screen description...", y=5)
    # Add more content...
```

3. Add navigation item to sidebar in `_render_sidebar()`:
```python
("New Screen", "new_screen_id"),
```

### Customizing Navigation Logic

Override `_on_next()` and `_on_prev()` methods to implement custom screen flow logic, similar to the GUI version's `on_next()` and `on_prev()` methods.

## Limitations

The initial implementation provides basic screen rendering and navigation. Advanced features from the GUI may need additional implementation:

- Interactive input fields (passwords, text entry)
- Real-time console output during long-running operations
- Progress bars and spinners
- Complex form validation
- Dynamic dependency screen insertion

These features can be added incrementally as needed.

## Testing

Test the ncurses interface:

```bash
# Verify modules load correctly
python3 -c "from knoe.ncurses_installer import run_ncurses_installer; print('OK')"

# Run the installer
./install.py --no-gui

# View help
./install.py --help
```

## Troubleshooting

**Terminal Too Small:**
If your terminal window is too small, the interface may not render correctly. Resize your terminal to at least 80x24 characters (larger recommended).

**Colors Not Showing:**
Some terminals may not support colors. The interface will fall back to monochrome display automatically.

**Keyboard Input Not Working:**
Ensure your terminal emulator is sending the correct escape sequences for arrow keys. Try using `h/j/k/l` as alternatives.

## Future Enhancements

Potential improvements for the ncurses interface:

1. **Interactive Forms** - Full input field support for passwords, text entry
2. **Real-time Logs** - Streaming console output during builds/deployments
3. **Progress Indicators** - Visual feedback for long operations
4. **Color Themes** - Customizable color schemes
5. **Mouse Support** - Click navigation in supported terminals
6. **Validation** - Form validation with error messages
7. **Help System** - Context-sensitive help screens