feat: add live watch mode for `kdm health`

[Rishiraj-Pathak-27]

Overview

Currently, the kdm health command provides only a one-time snapshot of Docker container and Kubernetes pod health.

A live monitoring / watch mode would significantly improve the usability of KDM for real-time debugging and observability.

---

Proposed Feature

Add support for a continuous monitoring mode using:

kdm health <target> --watch

or shorthand:

kdm health <target> -w

---

Example Usage

Watch all workloads

kdm health all --watch

Watch only Kubernetes pods

kdm health pods --watch

Watch only Docker containers

kdm health containers --watch

---

Expected Behavior

• Continuously refresh health output at fixed intervals
• Show updated container/pod statuses in real time
• Detect:
  • crashes
  • restarts
  • unhealthy workloads
  • newly created workloads
• Exit cleanly using Ctrl + C

---

Suggested Enhancements

Custom refresh interval

kdm health all --watch --interval 5

Where:

• 5 = refresh every 5 seconds

Terminal Improvements

• Clear and redraw the table on refresh
• Preserve colored health indicators
• Show timestamp of latest refresh

---

Why This Feature Matters

This would make kdm health more useful for:

• DevOps workflows
• local Kubernetes debugging
• monitoring development containers
• real-time troubleshooting

Instead of repeatedly running the command manually, users could monitor workload health continuously from a single terminal session.

---

Possible Implementation Ideas

• Use setInterval() for periodic refresh
• Re-render CLI tables dynamically
• Gracefully handle Docker/Kubernetes connection failures
• Support both Docker and Kubernetes sources independently

---

Current Behavior

Currently:

kdm health all

returns only a static snapshot of workload health.

---

Expected Improvement

After this feature:

kdm health all --watch

would behave similarly to:

• watch kubectl get pods
• docker stats
• live DevOps monitoring tools

while keeping the clean KDM CLI experience.

[utkarsh232005]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Extend the existing showHealth function with conditional watch mode behavior rather than creating separate components
• Use a simple setInterval + terminal clear pattern (matching watch.tsx's initial setup) for continuous refresh
• Add timestamp and exit hint to improve UX during live monitoring
• Handle SIGINT gracefully to clean up the interval and exit cleanly

Design Choices

Design Choice 1: Watch mode rendering approach

Options Considered:

1. Use Ink/React like the existing watch command - provides smooth rendering but adds complexity and changes the output format significantly
2. Use setInterval with terminal clear (\x1Bc) and re-render the existing table format - simpler, maintains consistency with non-watch health output

Chosen Option: 2

Rationale: The health command already has a clean table format; using terminal clear + table redraw keeps the output consistent between watch and non-watch modes while being simpler to implement.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Watch Mode to Health Command

Extend the existing health command with watch functionality, including CLI options, a refresh loop, timestamp display, and graceful exit handling.

Task 1: Add Commander Options for Watch Mode

Add the --watch and --interval flags to the health command registration.

• Update src/commands/health.ts in registerHealthCommand to add .option('-w, --watch', 'Enable live watch mode') and .option('-i, --interval <seconds>', 'Refresh interval in seconds', '3') to the command chain
• Modify the .action() handler to pass options to showHealth — Commander passes options as the second argument when options are defined

Task 2: Implement Watch Loop Logic

Add the core watch mode functionality that periodically fetches and displays health data.

• Update showHealth function signature to accept an options object containing watch (boolean) and interval (string/number)
• When watch mode is disabled, retain existing behavior (spinner, single fetch, render, exit)
• When watch mode is enabled:
  • Skip the spinner entirely to avoid visual noise during continuous refresh
  • Perform initial data fetch and render immediately
  • Set up a setInterval using the parsed interval value (default 3 seconds) to repeat the fetch-and-render cycle
  • Store the interval ID for cleanup

Task 3: Add Terminal Clearing and Timestamp Display

Implement the visual refresh behavior for watch mode.

• Before each render cycle in watch mode, clear the terminal using process.stdout.write('\x1Bc') (VT100 full reset, same pattern used in src/commands/watch.tsx)
• Add a header line showing the current timestamp before the table (e.g., "Last updated: HH:MM:SS")
• Add a footer hint showing "Press Ctrl+C to exit" and the current refresh interval
• Use existing chalk utilities for consistent styling with the rest of the CLI

Task 4: Implement Graceful Exit Handling

Ensure clean termination when the user presses Ctrl+C.

• Register a SIGINT handler using process.on('SIGINT', ...) when entering watch mode
• In the handler, clear the interval using clearInterval()
• Optionally print a farewell message before exiting
• Call process.exit(0) to terminate cleanly
• Remove the SIGINT listener if watch mode exits for other reasons (e.g., both data sources fail)

🤖 Prompt for AI agents

Extend the existing health command in `src/commands/health.ts` to support a live
watch mode via new CLI flags and a periodic refresh loop.

- In `registerHealthCommand`, chain `.option('-w, --watch', 'Enable live watch
mode')` and `.option('-i, --interval <seconds>', 'Refresh interval in seconds',
'3')` onto the command definition
- Update the `.action()` handler to receive and forward options to `showHealth`
- Update the `showHealth` function signature to accept an options object with
`watch` (boolean) and `interval` (string/number) fields
- When `watch` is false/undefined: preserve existing behavior (spinner, single
fetch, render, exit)
  - When `watch` is true:
    - Skip the spinner
    - Perform an immediate initial fetch and render
- Set up `setInterval` using the parsed interval value (defaulting to 3
seconds); store the returned interval ID
- Before each render cycle, clear the terminal with
`process.stdout.write('\x1Bc')`
- Print a header line with the current timestamp (e.g., "Last updated:
HH:MM:SS") and a footer hint ("Press Ctrl+C to exit" + current interval) using
`chalk` for styling
- Register a `process.on('SIGINT', ...)` handler that calls `clearInterval()` on
the stored ID, optionally prints a farewell message, and calls `process.exit(0)`
- Remove the SIGINT listener if watch mode exits early (e.g., both data sources
fail)

Phase 2: Add Test Coverage

Extend the existing test suite to cover the new watch mode functionality.

Task 1: Add Option Parsing Tests

Verify that the new CLI options are correctly registered and parsed.

• Add test in src/__tests__/health.test.ts to verify --watch flag is recognized on the health command
• Add test to verify --interval option accepts a numeric value
• Add test to verify default interval value of 3 seconds when --interval is not specified
• Follow existing test patterns using program.parseAsync() and Commander inspection

Task 2: Add Watch Mode Behavior Tests

Test the watch loop mechanics using mocked timers.

• Add test that verifies setInterval is called with correct interval when --watch is passed
• Add test that verifies terminal clear sequence (\x1Bc) is written in watch mode
• Add test that verifies timestamp is displayed in watch mode output
• Use vi.useFakeTimers() and vi.advanceTimersByTime() to simulate interval ticks without actual delays
• Mock process.stdout.write to capture terminal control sequences
• Follow existing mocking patterns for getRunningContainers, getRunningPods, and renderTable

🤖 Prompt for AI agents

Extend the existing test file `src/__tests__/health.test.ts` to cover option
parsing and watch mode behavior for the new watch functionality.

**Option Parsing Tests:**
- Add a test verifying the `--watch` (`-w`) flag is recognized by the health
command using `program.parseAsync()`
- Add a test verifying the `--interval` (`-i`) option accepts a numeric value
- Add a test verifying the default interval is `'3'` (seconds) when `--interval`
is not specified
- Follow existing Commander inspection patterns in the test file

**Watch Mode Behavior Tests:**
- Use `vi.useFakeTimers()` to control timer execution without real delays
- Mock `process.stdout.write` to capture terminal control sequences
- Mock `getRunningContainers`, `getRunningPods`, and `renderTable` following
existing patterns
- Add a test verifying `setInterval` is called with the correct millisecond
interval when `--watch` is passed
- Add a test verifying the VT100 terminal clear sequence (`\x1Bc`) is written to
stdout during watch mode
- Add a test verifying a timestamp string is present in the watch mode output
- Use `vi.advanceTimersByTime()` to simulate interval ticks and assert repeated
fetch-and-render cycles

Research

The project is a CLI tool (kdm) built with Commander.js, using cli-table3 and chalk for table rendering, and @vr_patel/tui for spinners. The health command in src/commands/health.ts fetches Docker containers via getRunningContainers() and Kubernetes pods via getRunningPods(), then renders a colored health status table. An existing watch command (src/commands/watch.tsx) uses Ink/React with setInterval polling, but for the health command's simpler table-based output, a lightweight setInterval + terminal clear approach is more appropriate and consistent with the existing health command's behavior.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Extend the existing health command in `src/commands/health.ts` to support a live
watch mode via new CLI flags and a periodic refresh loop.

- In `registerHealthCommand`, chain `.option('-w, --watch', 'Enable live watch
mode')` and `.option('-i, --interval <seconds>', 'Refresh interval in seconds',
'3')` onto the command definition
- Update the `.action()` handler to receive and forward options to `showHealth`
- Update the `showHealth` function signature to accept an options object with
`watch` (boolean) and `interval` (string/number) fields
- When `watch` is false/undefined: preserve existing behavior (spinner, single
fetch, render, exit)
  - When `watch` is true:
    - Skip the spinner
    - Perform an immediate initial fetch and render
- Set up `setInterval` using the parsed interval value (defaulting to 3
seconds); store the returned interval ID
- Before each render cycle, clear the terminal with
`process.stdout.write('\x1Bc')`
- Print a header line with the current timestamp (e.g., "Last updated:
HH:MM:SS") and a footer hint ("Press Ctrl+C to exit" + current interval) using
`chalk` for styling
- Register a `process.on('SIGINT', ...)` handler that calls `clearInterval()` on
the stored ID, optionally prints a farewell message, and calls `process.exit(0)`
- Remove the SIGINT listener if watch mode exits early (e.g., both data sources
fail)
===============================================================================

Task: 2

Extend the existing test file `src/__tests__/health.test.ts` to cover option
parsing and watch mode behavior for the new watch functionality.

**Option Parsing Tests:**
- Add a test verifying the `--watch` (`-w`) flag is recognized by the health
command using `program.parseAsync()`
- Add a test verifying the `--interval` (`-i`) option accepts a numeric value
- Add a test verifying the default interval is `'3'` (seconds) when `--interval`
is not specified
- Follow existing Commander inspection patterns in the test file

**Watch Mode Behavior Tests:**
- Use `vi.useFakeTimers()` to control timer execution without real delays
- Mock `process.stdout.write` to capture terminal control sequences
- Mock `getRunningContainers`, `getRunningPods`, and `renderTable` following
existing patterns
- Add a test verifying `setInterval` is called with the correct millisecond
interval when `--watch` is passed
- Add a test verifying the VT100 terminal clear sequence (`\x1Bc`) is written to
stdout during watch mode
- Add a test verifying a timestamp string is present in the watch mode output
- Use `vi.advanceTimersByTime()` to simulate interval ticks and assert repeated
fetch-and-render cycles

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!