weather-cli-16bit/README.md

A simple, intelligent weather CLI with smart location detection - no quotes needed

# weather-cli-16bit v0.3.24 🌤️

[![npm version](https://badge.fury.io/js/weather-cli-16bit.svg)](https://www.npmjs.com/package/weather-cli-16bit)
[![GitHub Actions](https://github.com/deephouse23/weather-cli/workflows/NPM%20Publish%20on%20PR%20Merge/badge.svg)](https://github.com/deephouse23/weather-cli/actions)
![License](https://img.shields.io/badge/license-MIT-blue)
![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)
![16bitweather](https://img.shields.io/badge/16bitweather-weather_suite-brightgreen)
![Testing](https://img.shields.io/badge/testing-Playwright-green.svg)

Part of the 16bitweather suite of weather tools

A beautiful command-line weather application with **horizontal layout**, **responsive design**, **comprehensive testing**, and **enhanced features** for any location.

**✨ Now with no quotes needed! Just type `weather San Ramon CA` from anywhere on your system.**

## 🎉 **What's New in v0.3.24** - Comprehensive Testing & Enhanced Display

### 🧪 **Major Testing Infrastructure**
- **Playwright Integration**: Complete end-to-end testing framework
- **Automated Testing**: Comprehensive test suites for CLI validation
- **Test Coverage**: Weather commands, error handling, and display formatting
- **CI/CD Ready**: Tests run automatically on publish

### 🎨 **Enhanced Display System**
- **Improved Formatting**: Better alignment and layout consistency
- **Responsive Design**: Optimized for all terminal sizes
- **Visual Polish**: Enhanced color coding and spacing
- **Error Presentation**: Better error message formatting

### 🔧 **Configuration & Development**
- **MCP Integration**: Enhanced Model Context Protocol support
- **Development Tools**: Improved testing and debugging capabilities
- **Package Optimization**: Streamlined dependencies and build process

## 🆕 **Previous Major Updates**

### **v0.3.21** - Smart Location Parsing
- **No quotes needed!** Type naturally: `weather San Ramon CA`
- **Smart location detection**: Just type `weather CA` for California
- **Global support**: Works with provinces, states, and country codes
- **Fixed version display**: Banner now shows correct version
- **Auto NPM publishing**: Merging PRs automatically publishes to npm

### **v0.3.1** - NPM Package Ready
- **NPM Package**: Now available as `weather-cli-16bit` on npm
- **One Command Setup**: Install globally with `npm install -g weather-cli-16bit`
- **Instant Access**: Use `weather` command from anywhere on your system
- **Auto-Updates**: Easy updates with `npm update -g weather-cli-16bit`

### **v0.3.0** - Security & Reliability Release
- **OS Keychain Integration**: API keys stored securely using `keytar`
- **Zero Exposure**: API keys never appear in logs or error messages
- **Input Sanitization**: Comprehensive protection against injection attacks
- **Secure Commands**: New `weather auth set` and `weather auth test` commands
- **No More Crashes**: Eliminated all `process.exit()` calls from libraries
- **Smart Retry Logic**: Automatic retry with exponential backoff for network issues
- **Enhanced Caching**: Size limits (100 entries), age limits (7 days), LRU eviction

## 🚀 **Installation**

### **Method 1: NPM Global Installation (Recommended)**
```bash
# Install globally from npm
npm install -g weather-cli-16bit

# Start using immediately
weather San Francisco CA
```

### **Method 2: From GitHub Source**
```bash
# Clone and install locally
git clone https://github.com/deephouse23/weather-cli.git
cd weather-cli
npm install
npm link  # Creates global symlink
```

### **Requirements**
- Node.js v14.0.0 or higher
- npm (comes with Node.js)
- Internet connection for weather data
- OpenWeatherMap API key (free at [openweathermap.org](https://openweathermap.org/api))

### **Setup**
```bash
# Secure API key setup (recommended)
weather auth set

# Test your API key
weather auth test

# Alternative: Copy environment template
cp .env.example .env
# Edit .env and add your OpenWeatherMap API key
# Get your free API key at: https://openweathermap.org/api
```

## 📖 **Usage Examples**

### 🇺🇸 **US States (no quotes needed!)**
```bash
weather CA                    # California
weather Texas                 # Texas (full name)
weather NY                    # New York
```

### 🏙️ **Cities (no quotes needed!)**
```bash
weather San Ramon CA          # San Ramon, California
weather New York              # Auto-detects NYC
weather Los Angeles CA        # LA with state
weather San Francisco         # Auto-detects SF
```

### 🌍 **International**
```bash
weather London                # Auto-detects UK
weather Tokyo                 # Auto-detects Japan
weather Paris                 # Auto-detects France
weather BC                    # British Columbia, Canada
weather Ontario               # Ontario, Canada
```

### 📊 **All Commands**
```bash
# Basic weather lookup - no quotes needed!
weather San Ramon             # City name only
weather San Ramon CA          # City, State
weather New York US           # City, Country Code
weather London                # International cities
weather 94583                 # US Zip codes
weather Tokyo                 # Major cities worldwide

# Get forecasts
weather forecast London       # 24-hour forecast
weather 5day Tokyo           # 5-day forecast

# Compare cities
weather compare "New York" London

# GPS coordinates
weather coords 37.7749,-122.4194

# Interactive mode
weather                       # No arguments starts interactive mode
weather interactive          # Explicit interactive mode

# Configuration
weather config               # Set default location and units

# Cache management
weather cache                # View cache statistics
weather cache -c            # Clear cache

# Authentication
weather auth set            # Store API key securely
weather auth test           # Validate your API key

# Help system
weather --help              # General help
weather [command] --help    # Command-specific help
```

## 🎨 **Enhanced Display System**

### **Large Terminal Display**
```
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                      │
│   ☀️  San Ramon, US                                    🌅 Sunrise: 06:16 AM                                           │
│   clear sky                                           🌇 Sunset: 08:10 PM                                            │
│   🌡️  82°F                                           ⚠️  Air Quality: Good (AQI: 1)                                  │
│   💭 Feels like: 82°F                                 🌡️  Min: 73°F                                                  │
│   💧 Humidity: 44%                                    🌡️  Max: 88°F                                                  │
│   📊 Pressure: 1015 hPa                               🧭 Wind Dir: 247°                                              │
│   💨 Wind: 5.99 mph                                   👁️  Visibility: 10km                                           │
│                                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### **Temperature Units**
```bash
# Automatic regional detection
weather "London"              # Auto-detects UK = Celsius
weather "New York"            # Auto-detects US = Fahrenheit

# Force specific units
weather "Tokyo" --celsius     # Force Celsius
weather "Paris" --fahrenheit  # Force Fahrenheit
weather "Berlin" -u metric    # Use metric (Celsius)
weather "Sydney" -u imperial  # Use imperial (Fahrenheit)
```

### **Responsive Design**
- **Large terminals** (>120 chars): Full horizontal layout with all details
- **Medium terminals** (80-120 chars): Medium layout with basic sections
- **Small terminals** (<80 chars): Compact layout with combined info

## 🧪 **Testing & Quality Assurance**

### **Comprehensive Test Suite**
```bash
# Run all tests
npm test                      # Core functionality tests
npm run test:e2e             # Playwright end-to-end tests
npm run test:e2e:ui          # Run tests with UI mode
npm run test:e2e:debug       # Debug mode for tests

# Individual test suites
node test-location-parser.js  # Location parsing validation
node test-modules.js         # Module functionality tests
```

### **Test Coverage**
- **Location Parsing**: 25+ test cases for location format validation
- **API Integration**: Weather data retrieval and error handling
- **Display Formatting**: Terminal rendering and responsive design
- **Authentication**: Secure API key management
- **Caching System**: Cache hit/miss scenarios and expiration
- **Error Handling**: Network failures, invalid inputs, API errors

### **Playwright E2E Testing**
- **Real CLI Testing**: Tests actual command execution
- **Cross-Platform**: Windows, macOS, and Linux compatibility
- **User Scenarios**: Complete user workflows from installation to usage
- **Error Scenarios**: Invalid inputs, network issues, API failures

## 🛠️ **Features**

### **🌤️ Weather Information**
- **Current weather** with detailed conditions
- **Temperature** with feels-like and min/max
- **Humidity, pressure, and wind** data
- **Sunrise and sunset** times
- **Air quality** with AQI ratings

### **🎨 Enhanced Display**
- **Horizontal layout** that fits your terminal
- **Responsive design** for any screen size
- **Color-coded information** with emojis
- **Prominent location display** with city/state highlighting
- **Improved formatting** with better alignment and spacing

### **📦 Smart Caching**
- **30-minute cache expiration** for fresh data
- **Cache statistics** and cleanup tools
- **Automatic cache management** with expiration
- **Cache hit performance** optimization

### **🔒 Enterprise Security**
- **OS Keychain Storage**: API keys stored securely in system keychain
- **Input Sanitization**: Protection against injection attacks
- **Zero Exposure**: API keys never appear in logs or error messages
- **Secure Authentication**: New `auth set` and `auth test` commands
- **Fallback Support**: Graceful fallback to environment variables
- **Cross-Platform**: Works on macOS, Windows, and Linux

## 🏗️ **Architecture**

### **Modular Structure**
```
src/
├── weather.js      # API calls and weather logic
├── cache.js        # Caching with expiration
├── display.js      # UI formatting and output
├── config.js       # Configuration management
├── api/
│   ├── auth.js     # Secure authentication
│   └── http.js     # HTTP client with retry logic
└── utils/
    ├── errors.js   # Error handling utilities
    ├── locationParser.js  # Smart location parsing
    └── validators.js      # Input validation
```

### **Testing Infrastructure**
```
tests/
├── simple-weather-test.spec.js    # Basic weather functionality
├── weather-validation.spec.js     # Input validation tests
├── playwright.config.js           # Playwright configuration
└── test-location-parser.js        # Location parsing unit tests
```

### **Performance Improvements**
- **Reduced API calls** with intelligent caching
- **Better error handling** with informative messages
- **Responsive design** that adapts to terminal size
- **Enhanced user experience** with clear requirements

## 📊 **Package Information**

### **NPM Package Details**
- **Package Name**: `weather-cli-16bit`
- **Global Command**: `weather`
- **Minimum Node Version**: v14.0.0
- **Supported Platforms**: macOS, Windows, Linux
- **Testing Framework**: Playwright + Custom Test Suites

### **Update Instructions**
```bash
# Check current version
npm list -g weather-cli-16bit

# Update to latest version
npm update -g weather-cli-16bit

# Uninstall if needed
npm uninstall -g weather-cli-16bit
```

## 🔧 **Configuration**

### **API Key Setup**

Set your OpenWeatherMap API key (get one free at [OpenWeatherMap](https://openweathermap.org/api)):

```bash
# Secure method (recommended) - stores in OS keychain
weather auth set

# Test your API key
weather auth test

# Alternative method - environment variable
export WEATHER_API_KEY=your_api_key_here
```

### **Default Settings**

Configure your default location and temperature units:

```bash
weather config

# This will prompt you to set:
# - Default location (e.g., "San Francisco, CA")
# - Default temperature units (Celsius/Fahrenheit)
```

## 📚 **API Documentation**

### **Command Reference**

| Command | Description | Example |
|---------|-------------|---------|
| `weather [location]` | Current weather (default if no command) | `weather "Paris"` |
| `weather now [location]` | Current weather (explicit) | `weather now "Berlin"` |
| `weather forecast [location]` | 24-hour forecast | `weather forecast "Tokyo"` |
| `weather 5day [location]` | 5-day forecast | `weather 5day "Sydney"` |
| `weather compare <city1> <city2>` | Compare two cities | `weather compare "LA" "NYC"` |
| `weather coords <lat,lon>` | Weather by GPS | `weather coords 51.5,-0.1` |
| `weather config` | Set defaults | `weather config` |
| `weather cache` | View cache stats | `weather cache` |
| `weather cache -c` | Clear cache | `weather cache -c` |
| `weather auth set` | Store API key | `weather auth set` |
| `weather auth test` | Test API key | `weather auth test` |

### **Options**

| Option | Description | Example |
|--------|-------------|---------|
| `-u, --units <type>` | Temperature units (metric/imperial/auto) | `weather "London" -u metric` |
| `--celsius` | Force Celsius display | `weather "NYC" --celsius` |
| `--fahrenheit` | Force Fahrenheit display | `weather "London" --fahrenheit` |
| `-f, --forecast` | Include 24-hour forecast | `weather "Tokyo" -f` |
| `-a, --alerts` | Show weather alerts | `weather "Miami" -a` |
| `--no-beta-banner` | Hide beta banner | `weather "Paris" --no-beta-banner` |

## 📈 **Performance**

### **v0.3.24 Performance Improvements**
- **Enhanced Testing**: Playwright integration for comprehensive validation
- **Improved Display**: Better formatting and alignment consistency
- **Optimized Caching**: Smart cache management with 90%+ hit rate
- **Sub-Second Responses**: Cached responses in <100ms
- **Memory Optimization**: Reduced peak memory usage
- **Smart Retry Logic**: Automatic recovery from network issues

## 🚀 **Development**

### **Prerequisites**
- Node.js (v14 or higher)
- npm
- OpenWeatherMap API key

### **Setup**
```bash
# Clone repository
git clone https://github.com/deephouse23/weather-cli.git
cd weather-cli

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your API key

# Run tests
npm test
npm run test:e2e

# Test installation
node index.js "New York, US"
```

### **Development Scripts**
```bash
npm run dev              # Development mode with auto-restart
npm test                 # Run core functionality tests
npm run test:e2e        # Run Playwright end-to-end tests
npm run test:e2e:ui     # Run tests with Playwright UI
npm run test:full       # Run all test suites
```

## 🤝 **Contributing**

### **Development Process**
1. Fork the repo
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Run tests: `npm test && npm run test:e2e`
4. Commit changes: `git commit -m 'Add amazing feature'`
5. Push: `git push origin feature/amazing-feature`
6. Open PR → Auto-publishes to npm when merged!

### **Testing Requirements**
- All new features must include tests
- Playwright tests for CLI functionality
- Unit tests for core logic
- Performance tests for caching and API calls

### **Automated Release Process**
This project uses GitHub Actions to automatically publish to npm when PRs are merged to main.

#### **Testing in CI**
- Uses keytar-free tests for GitHub Actions compatibility
- Installs system dependencies (libsecret) for full functionality
- Fallback publish strategy if tests fail
- Location parser tests ensure core functionality works

## 📝 **Changelog**

### **v0.3.24** (Latest) - Comprehensive Testing & Enhanced Display
- 🧪 **TESTING**: Added Playwright testing framework for end-to-end testing
- 🧪 **TESTING**: Comprehensive test suites for weather CLI validation
- 🎨 **DISPLAY**: Improved weather display formatting and layout alignment
- 🔧 **CONFIG**: Enhanced configuration management with MCP integration
- 📦 **DEPS**: Updated dependencies and configuration files
- 🐛 **FIX**: Various bug fixes and performance improvements

### **v0.3.21** - Smart Location Parsing
- 🔍 **SEARCH**: No quotes needed - type naturally: `weather San Ramon CA`
- 🔍 **SEARCH**: Smart location detection for states and countries
- 🔍 **SEARCH**: Global support for provinces, states, country codes
- 📝 **UX**: Fixed version display in banner
- 🤖 **CI**: Auto NPM publishing on PR merge

### **v0.3.1** - NPM Package Release
- 📦 **NPM**: Global installation as `weather-cli-16bit`
- 📦 **NPM**: Proper bin structure with cross-platform compatibility
- 📚 **DOCS**: Updated documentation with npm installation guide
- 🔧 **CONFIG**: Semantic versioning and Node.js requirements

### **v0.3.0** - Security & Reliability Release
- 🔒 **SECURITY**: OS keychain integration with `keytar`
- 🔒 **SECURITY**: Comprehensive input sanitization and validation
- ⚡ **RELIABILITY**: Eliminated all `process.exit()` calls
- ⚡ **RELIABILITY**: HTTP client with timeout and exponential backoff
- 📦 **CACHING**: Enhanced caching with size/age limits and LRU eviction

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details. Created by 16bitweather.

## 👨‍💻 **Author**

16bitweather

## 🌐 **Links**

- **NPM Package**: [weather-cli-16bit](https://www.npmjs.com/package/weather-cli-16bit)
- **Homepage**: [16bitweather.co](https://16bitweather.co)
- **Repository**: [GitHub](https://github.com/deephouse23/weather-cli)
- **Issues**: [GitHub Issues](https://github.com/deephouse23/weather-cli/issues)
- **API**: [OpenWeatherMap](https://openweathermap.org/api)

---

**Part of the 16bitweather suite of weather tools** 🌤️