nupst/readme.hints.md

# NUPST Project Hints

## Recent Refactoring (January 2026)

### Phase 1 - Quick Wins

1. **Prompt Utility (`ts/helpers/prompt.ts`)**
   - Extracted readline/prompt pattern from all CLI handlers
   - Provides `createPrompt()` and `withPrompt()` helper functions
   - Used in: `ups-handler.ts`, `group-handler.ts`, `service-handler.ts`, `action-handler.ts`,
     `feature-handler.ts`

2. **Constants File (`ts/constants.ts`)**
   - Centralized all magic numbers (timeouts, intervals, thresholds)
   - Contains: `TIMING`, `SNMP`, `THRESHOLDS`, `WEBHOOK`, `SCRIPT`, `SHUTDOWN`, `HTTP_SERVER`, `UI`,
     `NETWORK`, `UPSD`, `PAUSE`, `PROXMOX`
   - Used in: `daemon.ts`, `snmp/manager.ts`, `actions/*.ts`, `upsd/client.ts`

3. **Logger Consistency**
   - Replaced all `console.log/console.error` in `snmp/manager.ts` with proper `logger.*` calls
   - Debug output uses `logger.dim()` for less intrusive output

### Phase 2 - Type Safety

4. **Circular Dependency Fix (`ts/interfaces/nupst-accessor.ts`)**
   - Created `INupstAccessor` interface to break the circular dependency between `Nupst` and
     `NupstSnmp`
   - `NupstSnmp.nupst` property now uses the interface instead of `any`

5. **Webhook Payload Interface (`ts/actions/webhook-action.ts`)**
   - Added `IWebhookPayload` interface for webhook action payloads
   - Exported from `ts/actions/index.ts`

6. **CLI Handler Type Safety**
   - Replaced `any` types in `ups-handler.ts` and `group-handler.ts` with proper interfaces
   - Uses: `IUpsConfig`, `INupstConfig`, `ISnmpConfig`, `IActionConfig`, `IThresholds`,
     `ISnmpUpsStatus`

## Features Added (February 2026)

### Network Loss Handling
- `TPowerStatus` extended with `'unreachable'` state
- `IUpsStatus` has `consecutiveFailures` and `unreachableSince` tracking
- After `NETWORK.CONSECUTIVE_FAILURE_THRESHOLD` (3) failures, UPS transitions to `unreachable`
- Shutdown action explicitly won't fire on `unreachable` (prevents false shutdowns)
- Recovery is logged when UPS comes back from unreachable

### UPSD/NIS Protocol Support
- New `ts/upsd/` directory with TCP client for NUT (Network UPS Tools) servers
- `ts/protocol/` directory with `ProtocolResolver` for protocol-agnostic status queries
- `IUpsConfig.protocol` field: `'snmp'` (default) or `'upsd'`
- `IUpsConfig.snmp` is now optional (not needed for UPSD devices)
- CLI supports protocol selection during `nupst ups add`
- Config version bumped to `4.2` with migration from `4.1`

### Pause/Resume Command
- File-based signaling via `/etc/nupst/pause` JSON file
- `nupst pause [--duration 30m|2h|1d]` creates pause file
- `nupst resume` deletes pause file
- Daemon polls continue but actions are suppressed while paused
- Auto-resume after duration expires
- HTTP API includes pause state in response

### Proxmox VM Shutdown Action
- New action type `'proxmox'` in `ts/actions/proxmox-action.ts`
- Uses Proxmox REST API with PVEAPIToken authentication
- Shuts down QEMU VMs and LXC containers before host shutdown
- Supports: exclude IDs, configurable timeout, force-stop, TLS skip for self-signed certs
- Should be placed BEFORE shutdown actions in the action chain

## Architecture Notes

- **SNMP Manager**: Uses `INupstAccessor` interface (not direct `Nupst` reference) to avoid circular
  imports
- **Protocol Resolver**: Routes to SNMP or UPSD based on `IUpsConfig.protocol`
- **CLI Handlers**: All use the `helpers.withPrompt()` utility for interactive input
- **Constants**: All timing values should be referenced from `ts/constants.ts`
- **Actions**: Use `IActionConfig` from `ts/actions/base-action.ts` for action configuration
- **Config version**: Currently `4.2`, migrations run automatically

## File Organization

```
ts/
├── constants.ts          # All timing/threshold constants
├── interfaces/
│   └── nupst-accessor.ts # Interface to break circular deps
├── helpers/
│   ├── prompt.ts         # Readline utility
│   └── shortid.ts        # ID generation
├── actions/
│   ├── base-action.ts    # Base action class, IActionConfig, TPowerStatus
│   ├── webhook-action.ts # Includes IWebhookPayload
│   ├── proxmox-action.ts # Proxmox VM/LXC shutdown
│   └── ...
├── upsd/
│   ├── types.ts          # IUpsdConfig
│   ├── client.ts         # NupstUpsd TCP client
│   └── index.ts
├── protocol/
│   ├── types.ts          # TProtocol = 'snmp' | 'upsd'
│   ├── resolver.ts       # ProtocolResolver
│   └── index.ts
├── migrations/
│   ├── migration-runner.ts
│   └── migration-v4.1-to-v4.2.ts  # Adds protocol field
└── cli/
    └── ...               # All handlers use helpers.withPrompt()
```