Skip to content

PROJECT_STATUS.md

Latest commit

 

History

History
323 lines (270 loc) · 11.6 KB

PROJECT_STATUS.md

File metadata and controls

323 lines (270 loc) · 11.6 KB
Raw

KDE BBS Client - Project Status

Last Updated: 2026-01-14 Status: ✅ Initial Implementation Complete (Python 3.13+ Compatible) Version: 0.1.0

Recent Updates

Font Size Control (Latest)

  • Feature: Adjustable terminal font size with keyboard shortcuts
  • Keyboard Shortcuts:
    • Ctrl+Plus or Ctrl+= - Increase font size
    • Ctrl+Minus - Decrease font size
    • Ctrl+0 - Reset to default (10pt)
  • Configuration:
    • Font size saved globally in config file
    • Range: 6pt to 48pt
    • Increments of 2pt per keystroke
  • Feedback: Status bar shows current font size when changed

ANSI Color Support

  • Feature: Full ANSI color and formatting support
  • Implementation: Custom ANSI escape sequence parser (ansi_parser.py)
  • Capabilities:
    • 16-color standard palette (normal + bright colors)
    • 256-color extended palette
    • 24-bit RGB true color
    • Text attributes: bold, underline, reverse video
    • Proper rendering of BBS graphics and ANSI art
  • Result: BBS systems now display with full color and formatting

Bug Fixes

  • Text visibility: Fixed invisible text in configuration dialog and BBS chooser list
  • Input mode: Changed from line-oriented to character-by-character telnet input for proper BBS interaction
  • Backspace handling: Fixed backspace display by properly handling BS (0x08) and DEL (0x7F) control characters from server - now deletes previous character instead of showing empty squares. Based on analysis of iscabbs-client C codebase.

Python 3.13+ Compatibility Fix

  • Issue: ModuleNotFoundError: No module named 'telnetlib'
  • Cause: Python 3.13+ removed the deprecated telnetlib module
  • Solution: Implemented custom socket-based telnet client with full protocol support
  • Benefits:
    • No external dependencies required
    • Full telnet protocol negotiation (IAC, DO, DONT, WILL, WONT, subnegotiation)
    • Better control over connection handling
    • Works with Python 3.10+ including 3.14.2

Overview

KDE BBS Client is a modern PyQt6-based client for connecting to old school telnet-based BBS systems. The application provides a clean, user-friendly interface for managing and connecting to multiple BBS systems.

Implementation Status

✅ Completed Features

1. Project Infrastructure

  • Package Manager: Using uv for Python dependency management
  • Code Quality: Using ruff for linting and formatting
  • Python Version: 3.10+ compatible
  • All syntax checks passing: uv run ruff check . returns clean

2. Configuration System (config.py)

  • YAML-based configuration file at ~/.config/kdebbsclient/client-config.yaml
  • Support for multiple BBS systems in a single config file
  • Each BBS entry stores:
    • Name (friendly identifier)
    • Address (FQDN, IPv4, or IPv6)
    • Port (defaults to 23)
    • Username
    • Password
  • Automatic config directory creation on first run
  • Safe config file read/write with error handling

3. Initial Configuration Dialog (ui/config_dialog.py)

  • Appears on first run when no config file exists
  • Styled form with fields for:
    • BBS Name (required)
    • BBS Address (required, supports FQDN/IPv4/IPv6)
    • Port (optional, defaults to 23)
    • Username (optional)
    • Password (optional, hidden input)
  • Input validation before submission
  • Modern, clean UI styling

4. BBS Chooser Window (ui/bbs_chooser.py)

  • Main window showing list of configured BBS systems
  • Display format: Name\nAddress:Port for each BBS
  • Features:
    • Add New BBS button - launches config dialog to add more systems
    • Connect button - initiates connection to selected BBS
    • Double-click to connect
    • Selection-based enable/disable of connect button
  • Automatically reloads list after adding new BBS

5. Telnet Connection Handler (telnet_client.py)

  • Custom socket-based implementation (Python 3.13+ compatible, no telnetlib dependency)
  • Threaded telnet client (runs in QThread)
  • Full telnet protocol support:
    • IAC (Interpret As Command) processing
    • DO/DONT/WILL/WONT option negotiation
    • Subnegotiation (SB/SE) handling
    • Escaped IAC (255) support
  • PyQt signals for:
    • data_received - BBS output data
    • connection_established - successful connection
    • connection_error - connection failures with error messages
    • connection_closed - connection terminated
  • Error handling for:
    • Connection timeout
    • Host resolution failures (DNS)
    • Connection refused
    • Read/write errors
  • Non-blocking read operations with buffering
  • Supports UTF-8 and Latin-1 character encoding

6. Terminal Window (ui/terminal_window.py)

  • Main terminal interface for BBS interaction
  • Components:
    • Text Display: Monospace font, read-only, suitable for large volumes of text
    • Input Line: Text field for user input, sends on Enter
    • Status Bar: Shows connection status
  • Features:
    • Arrow key support (↑↓←→) sends ANSI escape sequences
    • Auto-scrolling to bottom as new text arrives
    • Graceful disconnect on window close
    • Character encoding fallback (UTF-8 → Latin-1)
  • Classic terminal styling (green text on black background)

7. Build & Run Scripts

  • setup.sh - One-time setup using uv
  • run.sh - Quick application launcher
  • Both scripts check for uv installation
  • Executable permissions set

8. Documentation

  • README.md - Original specification
  • USAGE.md - Comprehensive user guide
  • PROJECT_STATUS.md - This file

9. ANSI Color Support (ansi_parser.py)

  • Full ANSI escape sequence parsing for terminal colors and formatting
  • Supported features:
    • Standard 16 colors (8 normal + 8 bright)
    • 256-color palette support
    • 24-bit RGB true color support
    • Text formatting: bold, underline
    • Reverse video mode
    • Reset codes
  • Color codes supported:
    • Foreground: 30-37 (standard), 90-97 (bright)
    • Background: 40-47 (standard), 100-107 (bright)
    • Extended colors: 38;5;N (256-color), 38;2;R;G;B (RGB)
  • Proper BBS graphics and ANSI art rendering

📋 Planned Features (Not Yet Implemented)

From README TODO section:

  • Editor Integration: Auto-detect when user creates a new post and spawn $EDITOR for editing

Additional potential enhancements:

  • SSH Support: Alternative to telnet for secure connections
  • Session Logging: Save BBS sessions to log files
  • Macros/Hotkeys: Customizable shortcuts for common commands
  • Connection Profiles: Quick connect from system tray or menu
  • Auto-login: Automated login sequence using saved credentials

Technical Architecture

Technology Stack

  • Language: Python 3.10+ (tested with 3.14.2)
  • GUI Framework: PyQt6
  • Package Manager: uv
  • Code Quality: ruff
  • Config Format: YAML
  • Protocol: Custom socket-based telnet implementation (Python 3.13+ compatible)

File Structure

kde-bbs-client/
├── kdebbsclient.py         # Main entry point, application lifecycle
├── config.py               # Configuration file management
├── telnet_client.py        # Threaded telnet connection handler
├── ansi_parser.py          # ANSI escape sequence parser for colors
├── ui/
│   ├── __init__.py
│   ├── config_dialog.py    # Initial BBS setup dialog
│   ├── bbs_chooser.py      # BBS selection window
│   └── terminal_window.py  # Main terminal interface with ANSI support
├── pyproject.toml          # Project metadata and dependencies
├── requirements.txt        # Legacy pip requirements (for reference)
├── setup.sh                # Setup script (uv-based)
├── run.sh                  # Run script (uv-based)
├── .gitignore              # Git ignore patterns
├── README.md               # Original specification
├── USAGE.md                # User guide
└── PROJECT_STATUS.md       # This file

Dependencies

Runtime:

  • PyQt6 >= 6.4.0
  • PyYAML >= 6.0

Development:

  • ruff >= 0.1.0

Code Quality Standards

  • Line length: 100 characters
  • Target Python version: 3.10
  • Ruff linting rules: E, F, W, I, N, UP
  • Exception: N802 ignored (allows PyQt method names like closeEvent, keyPressEvent)

Current Limitations

  1. No Editor Integration: The TODO feature for detecting post creation and spawning $EDITOR is not implemented
  2. Basic Error Messages: Connection errors are shown but could be more user-friendly
  3. No Session Persistence: Terminal history is lost when window closes
  4. Single Connection: Can't connect to multiple BBS systems simultaneously
  5. Telnet Only: No SSH or other secure protocol support

Testing Status

Manual Testing Checklist

  • Application launches successfully
  • Config dialog appears on first run
  • Config file created at correct location
  • BBS systems added via dialog
  • BBS chooser displays configured systems
  • Syntax checking passes (ruff check)
  • Actual telnet connection to live BBS (requires test BBS server)
  • Terminal display and input (requires live BBS)
  • Arrow key navigation (requires live BBS)
  • Multiple BBS management workflow

Known Issues

None reported yet (application not tested with live BBS server)

Next Steps

Immediate Priorities

  1. Test with Live BBS: Connect to an actual BBS to verify telnet functionality and ANSI rendering
  2. User Testing: Get feedback on UI/UX and ANSI color display

Medium-term Goals

  1. Editor Integration: Implement the $EDITOR spawning feature from README TODO
  2. Session Logging: Save BBS sessions to files
  3. Auto-login: Automated login using saved credentials
  4. Better Error Handling: More informative error messages and recovery options
  5. ANSI Art Optimization: Fine-tune color palette for optimal ANSI art display

Long-term Goals

  1. SSH Support: Secure alternative to telnet
  2. Multi-session: Support multiple concurrent BBS connections
  3. Macros: Customizable hotkeys and command sequences
  4. Plugin System: Allow extensions for custom BBS features

Development Commands

# Setup project
./setup.sh

# Run application
./run.sh
# OR
uv run python kdebbsclient.py

# Check code quality
uv run ruff check .

# Auto-fix issues
uv run ruff check --fix .

# Install dev dependencies
uv sync --extra dev

Configuration File Example

Location: ~/.config/kdebbsclient/client-config.yaml

bbs_systems:
  - name: Example BBS
    address: bbs.example.com
    port: 23
    username: myusername
    password: mypassword
  - name: Local Test BBS
    address: 192.168.1.100
    port: 2323
    username: testuser
    password: testpass

Git Status

  • Current Branch: main
  • Recent Commits: Initial commit
  • Untracked Files: README.md (now many more files created)
  • Ready for: Initial commit of implementation

Notes

  • User selected Python with PyQt6 over C++/Qt6
  • User selected multiple BBS support over single BBS
  • User selected config dialog + BBS chooser + telnet connection as initial scope
  • Editor integration deferred to future iteration
  • Project uses modern Python tooling (uv, ruff) per user request
  • All code passes ruff syntax checking with zero errors

Success Criteria Met

✅ Configuration file at $HOME/.config/kdebbsclient/client-config.yaml ✅ Config dialog on first run with all specified fields ✅ Password field hidden on entry ✅ Config file created on Submit ✅ BBS chooser displays list of systems with name and address ✅ Connect button to initiate telnet connection ✅ Terminal display window for BBS output ✅ Nicely styled UI throughout ✅ Support for FQDN, IPv4, and IPv6 addresses

The implementation meets all requirements from the README specification for the selected initial feature set.