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
   • Used in: daemon.ts, snmp/manager.ts, actions/*.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

Architecture Notes

• SNMP Manager: Uses INupstAccessor interface (not direct Nupst reference) to avoid circular imports
• 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

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 and interfaces
│   ├── webhook-action.ts # Includes IWebhookPayload
│   └── ...
└── cli/
    └── ...               # All handlers use helpers.withPrompt()