Migrate scripts to unified CLI/TUI using cac and @clack/prompts #535

Overview

Consolidate all Nostream scripts into a single, user-friendly CLI tool with an interactive TUI fallback. This improves UX and reduces script maintenance burden.

Tech Stack

• cac: Command-line argument parser (lightweight, flexible)
• @clack/prompts: Interactive prompts for TUI mode

Scope

Scripts to Migrate (Priority)

• start — Start Nostream (with optional --tor, --i2p flags)
• stop — Stop Nostream
• export — Export events
• import — Import events
• seed — Seed relay with test data
• setup — Initial Nostream configuration
• print-tor-hostname — Display Tor v3 onion address
• Development scripts (testing, seeding, database utilities)

Output Structure

src/cli/
├── index.ts              # Main CLI entry point
├── commands/
│   ├── start.ts
│   ├── stop.ts
│   ├── export.ts
│   ├── import.ts
│   ├── seed.ts
│   ├── setup.ts
│   ├── info.ts           # Print Tor hostname, relay info
│   └── dev.ts            # Development utilities (seed, clean-db, etc)
├── tui/
│   ├── main.ts           # Main menu
│   ├── menus/
│   │   ├── start.ts
│   │   ├── configure.ts
│   │   ├── manage.ts
│   │   └── dev.ts
│   └── state.ts          # Shared TUI state
├── utils/
│   ├── config.ts         # Load/save configuration
│   ├── validation.ts     # Input validation
│   └── formatting.ts     # Output formatting
└── types.ts              # Shared types

CLI Interface Design

Proposed CLI Flags

# Basic usage
nostream --help                    # Show all commands
nostream start --help              # Show command-specific help
nostream start --tor               # Start with Tor enabled
nostream start --i2p --tor         # Start with both Tor and I2P
nostream start --debug             # Start in debug mode
nostream start --port 8008         # Override default port

# Configuration
nostream setup                      # Interactive setup wizard
nostream config set payments.enabled true
nostream config get payments.processor
nostream config list               # Show all settings

# Management
nostream export --format json --output events.json
nostream import --file events.json
nostream seed --count 100          # Generate test events
nostream stop                      # Graceful shutdown
nostream info --tor-hostname       # Print Tor v3 address

# Development
nostream dev db:clean              # Clean database
nostream dev db:reset              # Reset to initial state
nostream dev seed:relay            # Seed with test data

TUI Flow (when no flags provided)

┌─────────────────────────────────────┐
│  🚀 Nostream Control Center          │
├─────────────────────────────────────┤
│                                     │
│  What would you like to do?         │
│                                     │
│  ❯ Start relay                      │
│    Stop relay                       │
│    Configure settings               │
│    Manage data (export/import)      │
│    Development tools                │
│    View relay info                  │
│    Exit                             │
│                                     │
└─────────────────────────────────────┘

[Start] → Network options → (Tor? I2P? Debug?)
         → Confirm → Start with spinner

[Configure] → Category select (payments/limits/network)
            → Setting edit with validation
            → Save → Restart prompt?

[Manage] → Export/Import selector
         → File path/format selection
         → Confirm → Execute

[Dev] → db:clean / db:reset / seed options
      → Confirm (warn: destructive operations)
      → Execute

[Relay Info] → Show:
             • Relay name, version, pubkey
             • Tor v3 hostname (if enabled)
             • Payment status
             • Event count
             • Uptime

Features

• Single entry point: nostream or npm run cli
• --help flag shows all commands
• <command> --help shows command-specific help
• TUI interactive mode when no flags provided
• Full settings configuration via CLI
• Settings validation on input
• Graceful error messages
• Colored output with spinners for long operations
• Confirmation prompts for destructive operations (delete, reset)

Configuration Management

The CLI must support all existing settings without editing files:

• Network settings (port, relay_url, network type)
• Payment configuration (enabled, processor, fees)
• Event limits (content length, message size)
• NIP support toggles
• Admin pubkey configuration
• Database settings

Example flow:

nostream config list                    # See all settings
nostream config get payments.processor  # Get single value
nostream config set payments.enabled true --restart  # Set and restart
nostream config validate               # Validate all settings

Documentation Updates

• Update README with new CLI usage
• Create CLI.md with all commands and flags
• Add examples for common workflows
• Document TUI navigation
• Remove old script documentation

Acceptance Criteria

• All existing scripts migrated and working
• CLI supports all original functionality
• TUI launches when no flags provided
• Help system complete and clear
• Settings management complete
• Error handling robust
• Documentation complete
• Old scripts removed from project
• No regression in functionality
• CLI accessible via npm run cli or global install

Notes

• Consider using chalk or colorette for colored output
• Use ora for loading spinners
• Keep TUI state minimal and synchronized with filesystem config
• Ensure all async operations have proper error handling
• Consider adding a --json flag for machine-readable output in critical commands