feat(core): Centralize timeouts/constants, add CLI prompt helpers, and introduce webhook/script actions with safety and SNMP refactors

readme.hints.md

@@ -0,0 +1,58 @@
+# 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()
+```