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()