detector/readme.hints.md

# Project Readme Hints

## Project Overview
- **@uptime.link/detector** - A network detection utility that checks port availability and service types locally
- Version: 2.0.2 (recently updated from 2.0.1)
- Type: ESM module (switched from CommonJS in v2.0.0)
- Main purpose: Detect if ports are active/available and identify service types without external services

## Key Components
1. **Detector Class** (`ts/detector.classes.detector.ts`):
   - `isActive(urlArg: string, options?: IDetectorOptions)`: Returns detailed IDetectorResult with service type detection
   - `isActiveSimple(urlArg: string)`: Returns boolean for backward compatibility
   - `detectType(urlArg: string)`: Detects service type (HTTP, HTTPS, SSH, FTP, etc.)
   - For localhost: Uses `isLocalPortUnused()` (inverted to check if port is active)
   - For remote: Uses `isRemotePortAvailable()`

2. **Service Detection Features**:
   - HTTP/HTTPS protocol detection with TLS support
   - SSH service identification via banner detection
   - Service fingerprinting for common protocols (FTP, SMTP, MySQL, etc.)
   - Banner grabbing for unknown services
   - Support for custom timeout configuration

3. **Dependencies** (`ts/detector.plugins.ts`):
   - `@push.rocks/smartnetwork`: Network utilities for port checking
   - `@push.rocks/smarturl`: URL parsing utilities
   - Node.js built-ins: net, tls, http, https for protocol detection

4. **Interfaces** (`ts/detector.interfaces.ts`):
   - `ServiceType`: Enum of supported service types
   - `IDetectorResult`: Detailed result object with service info
   - `IDetectorOptions`: Configuration options for detection

## Recent Changes
- **v2.0.0**: Breaking change - switched to ESM modules
- **v2.0.1**: Minor update to commitinfo
- **v2.0.2**: Added service type detection, protocol fingerprinting, and enhanced API

## Testing
- Comprehensive test suite with 19 tests covering:
  - Basic port detection (local and remote)
  - Backward compatibility with `isActiveSimple()`
  - Service type detection for HTTP, HTTPS, SSH
  - Error handling and edge cases
  - Performance benchmarks
  - Common development ports
  - Database service detection (MySQL, Redis)
- Uses `@git.zone/tstest` with tap-style testing
- Tests ensure serviceType is always returned when detectServiceType option is true
- Handles non-standard URL schemes with default ports

## Notes
- Project uses pnpm for package management
- Build supports web targets (`--web` flag)
- No external online services required for detection
- All network detection happens locally without third-party APIs