# CLI Port Override Implementation

## Overview

This document describes the implementation of the `-p <port>` command line option for the C Nostr Relay, which allows overriding the default relay port during first-time startup only.

## Design Principles

1. **First-time startup only**: Command line options only affect the initial configuration event creation
2. **Event-based persistence**: After first startup, all configuration is managed through database events
3. **Proper encapsulation**: All configuration logic is contained within `config.c`
4. **Extensible design**: The CLI options structure can easily accommodate future command line options

## Implementation Details

### Files Modified

#### `src/config.h`
- Added `cli_options_t` structure to encapsulate command line options
- Updated `first_time_startup_sequence()` function signature

#### `src/config.c`
- Updated `first_time_startup_sequence()` to accept CLI options parameter
- Updated `create_default_config_event()` to accept CLI options parameter
- Implemented port override logic in DEFAULT_CONFIG_VALUES array processing

#### `src/default_config_event.h`
- Updated function signature for `create_default_config_event()`
- Added proper header include for `cli_options_t` definition

#### `src/main.c`
- Added command line parsing for `-p <port>` and `--port <port>`
- Updated help text to document the new option
- Added proper error handling for invalid port values
- Updated function call to pass CLI options to configuration system

### CLI Options Structure

```c
typedef struct {
    int port_override;  // -1 = not set, >0 = port value
    // Future CLI options can be added here
} cli_options_t;
```

### Command Line Usage

```bash
# First-time startup with port override
./c_relay_x86 -p 9090
./c_relay_x86 --port 9090

# Show help (includes new option)
./c_relay_x86 --help

# Show version
./c_relay_x86 --version
```

### Error Handling

The implementation includes robust error handling for:
- Missing port argument: `./c_relay_x86 -p`
- Invalid port format: `./c_relay_x86 -p invalid_port`
- Out-of-range ports: `./c_relay_x86 -p 0` or `./c_relay_x86 -p 99999`

## Behavior Verification

### First-Time Startup
When no database exists:
1. Command line is parsed and `-p <port>` is processed
2. CLI options are passed to `first_time_startup_sequence()`
3. Port override is applied in `create_default_config_event()`
4. Configuration event is created with overridden port value
5. Relay starts on the specified port
6. Port setting is persisted in database for future startups

### Subsequent Startups
When database already exists:
1. Command line is still parsed (for consistency)
2. Existing relay path is taken
3. Configuration is loaded from database events
4. CLI options are ignored
5. Relay starts on port from database configuration

## Testing Results

### Test 1: First-time startup with port override
```bash
./c_relay_x86 -p 9090
```
**Result**: ✅ Relay starts on port 9090, configuration stored in database

### Test 2: Subsequent startup ignores CLI options
```bash
./c_relay_x86 -p 7777
```
**Result**: ✅ Relay starts on port 9090 (from database), ignores `-p 7777`

### Test 3: Error handling
```bash
./c_relay_x86 -p invalid_port
./c_relay_x86 -p
```
**Result**: ✅ Proper error messages and help text displayed

### Test 4: Help text
```bash
./c_relay_x86 --help
```
**Result**: ✅ Displays updated help with `-p, --port PORT` option

## Database Verification

The port setting is correctly stored in the database:
```sql
SELECT json_extract(tags, '$') FROM events WHERE kind = 33334;
```
Shows the overridden port value in the configuration event tags.

## Future Extensions

The `cli_options_t` structure is designed to be easily extended:

```c
typedef struct {
    int port_override;        // -1 = not set, >0 = port value
    char* description_override; // Future: relay description override
    int max_connections_override; // Future: connection limit override
    // Add more options as needed
} cli_options_t;
```

## Key Design Benefits

1. **Separation of Concerns**: Main function handles CLI parsing, config system handles application
2. **First-time Only**: Prevents confusion about configuration precedence
3. **Event-based Architecture**: Maintains consistency with the relay's event-based configuration system
4. **Extensible**: Easy to add new command line options in the future
5. **Robust**: Comprehensive error handling and validation
6. **Documented**: Clear help text explains behavior to users

## Summary

The `-p <port>` command line option implementation successfully provides a way to override the default relay port during first-time startup while maintaining the event-based configuration architecture for ongoing operation. The implementation is robust, well-tested, and ready for production use.