Improvement: Make `kdm config setup` the Default Configuration Flow

[utkarsh232005]

Summary

Currently, KDM provides two different configuration methods:

1. Interactive configuration flow:

   kdm config setup

2. Direct credential configuration:

   kdm config set <credentials>

Having multiple configuration approaches is creating confusion among users, especially new users who are unsure which method should be used for proper setup.

To simplify the onboarding experience and maintain consistency, the default configuration workflow should be migrated entirely to the interactive kdm config setup flow.

---

Problem

Users currently face confusion because:

• There are multiple ways to configure the same service
• The direct config set command requires users to already know:
  • Required credentials
  • Correct key names
  • Input formats
• Interactive guidance is missing in direct configuration mode
• Documentation becomes harder to maintain due to multiple setup approaches
• Support requests increase because users misconfigure credentials

Example confusion:

kdm config set discord webhook_url=...

vs

kdm config setup

Users are unclear about:

• Which command is recommended
• Which flow is officially supported
• Which method stores credentials correctly

---

Proposed Solution

Make the interactive setup flow the primary and default configuration experience.

Recommended Changes

• Deprecate manual credential-based setup commands
• Redirect users toward:

  kdm config setup

• Add guided prompts for all supported services
• Provide credential generation instructions during setup
• Standardize configuration storage and validation logic

---

Suggested CLI Behavior

Current

kdm config set discord webhook_url=...

Proposed

kdm config setup

Interactive flow:

Select Service:
> Discord

Then:

Discord Setup Instructions:

1. Open Discord
2. Go to Server Settings
3. Navigate to Integrations → Webhooks
4. Create a new webhook
5. Copy the webhook URL

Then:

Enter Discord Webhook URL:

---

Benefits

• Cleaner and more beginner-friendly UX
• Reduces setup-related confusion
• Prevents invalid credential formatting
• Easier documentation and maintenance
• Consistent onboarding experience
• Better scalability for future integrations

---

Additional Suggestions

• Keep config set internally for advanced/debug usage only
• Add validation during interactive input
• Add support for reconfiguration/edit mode
• Add setup completion confirmation messages

---

Expected Outcome

Users should have a single, guided, and consistent configuration experience using:

kdm config setup

This should become the officially recommended and default setup workflow across the project.

[utkarsh232005]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Enhance config setup with credential generation instructions displayed before each prompt, following the ticket's example format for Discord
• Add reconfiguration detection that checks for existing configuration and confirms before overwriting
• Implement soft deprecation for config set on credential keys by displaying warnings while still allowing the operation
• Preserve config set without warnings for non-credential keys like alert_cooldown to support advanced usage

Design Choices

Design Choice 1: Which keys should remain settable via `config set`?

Options Considered:

1. Block all keys in config set and require config setup for everything
2. Allow only non-credential keys (alert_cooldown) via config set, deprecate credential keys
3. Allow all keys but show deprecation warning for credential keys only

Chosen Option: 2

Rationale: Allow only alert_cooldown without warning, show deprecation warnings for credential keys (notification_service, discord_webhook, email_host, email_port, email_user, email_to) — this maintains backward compatibility for legitimate advanced use while guiding users toward the interactive flow for credentials.

💡 User Tips

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

Implementation Steps

Phase 1: Enhance Interactive Setup Flow

This phase improves the config setup command by adding credential generation instructions and reconfiguration support, making it a more complete and guided experience.

Task 1: Add Credential Generation Instructions

Add step-by-step instructions that display before prompting for credential input, helping users obtain the required values.

• Update src/commands/config.ts to display Discord webhook creation instructions before the webhook URL prompt (instructions: Open Discord → Server Settings → Integrations → Webhooks → Create/Copy URL)
• Update src/commands/config.ts to display Email SMTP setup instructions before the SMTP prompts (instructions: guidance on obtaining SMTP credentials from common providers)
• Use chalk for styled instruction output with clear visual separation (e.g., boxed or indented format)
• Keep instructions concise but actionable, matching the example format in the ticket

Task 2: Add Reconfiguration Detection and Confirmation

Detect existing configuration and prompt users before overwriting, providing a smoother reconfiguration experience.

• Update src/commands/config.ts to check getConfig() for existing notification_service value at the start of the setup flow
• If a service is already configured, display current configuration status and prompt user to confirm reconfiguration using a confirmation message (can use select with Yes/No options since confirm isn't currently used in the codebase)
• Allow users to cancel without making changes if they don't want to reconfigure
• Proceed with normal setup flow if user confirms or if no existing configuration exists

🤖 Prompt for AI agents

This phase enhances `src/commands/config.ts` to make `config setup` a more
complete, guided experience by adding credential generation instructions and
reconfiguration detection.

**Task 1: Add Credential Generation Instructions**
- In `src/commands/config.ts`, before the Discord webhook URL prompt, display
step-by-step instructions using `chalk` for styled output:
- Instructions: Open Discord → Server Settings → Integrations → Webhooks →
Create/Copy URL
- Before the Email SMTP prompts, display SMTP setup instructions using `chalk`:
  - Instructions: guidance on obtaining SMTP credentials from common providers
- Use clear visual separation for instructions (e.g., boxed or indented format)
- Keep instructions concise but actionable, matching the example format in the
ticket

**Task 2: Add Reconfiguration Detection and Confirmation**
- At the start of the `config setup` flow in `src/commands/config.ts`, call
`getConfig()` to check for an existing `notification_service` value
- If a service is already configured:
  - Display the current configuration status to the user
- Prompt the user to confirm reconfiguration using a `select` prompt with Yes/No
options (do not use `confirm` as it is not currently used in the codebase)
  - If the user declines, exit the setup flow without making any changes
- If no existing configuration is found, or if the user confirms, proceed with
the normal setup flow

Phase 2: Deprecate Direct Credential Configuration

This phase adds deprecation warnings to config set for credential-related keys, redirecting users toward the guided config setup flow while preserving functionality for non-credential settings.

Task 1: Define and Enforce Credential Key Restrictions

Categorize config keys and add appropriate handling for each category in the config set command.

• Update src/commands/config.ts to define a list of credential keys: notification_service, discord_webhook, email_host, email_port, email_user, email_to
• Define non-credential keys that remain freely settable: alert_cooldown
• When a credential key is passed to config set, display a deprecation warning using chalk.yellow explaining that kdm config setup is the recommended method
• Include the exact command (kdm config setup) in the warning message for easy reference
• Still execute the set operation after the warning to maintain backward compatibility (soft deprecation)

Task 2: Update Tests for New Behavior

Extend test coverage to verify the new deprecation warnings and enhanced setup flow.

• Update src/__tests__/config.test.ts to verify deprecation warning is displayed when setting credential keys via config set
• Add tests to verify no warning is shown when setting alert_cooldown via config set
• Add tests to verify reconfiguration detection prompts user when existing config exists
• Add tests to verify setup instructions are displayed before credential prompts

🤖 Prompt for AI agents

This phase updates `src/commands/config.ts` to implement soft deprecation for
credential keys in the `config set` command, and extends
`src/__tests__/config.test.ts` to cover the new behavior.

**Task 1: Define and Enforce Credential Key Restrictions**
- In `src/commands/config.ts`, define a list of credential keys:
`notification_service`, `discord_webhook`, `email_host`, `email_port`,
`email_user`, `email_to`
- Define non-credential keys that remain freely settable without any warning:
`alert_cooldown`
- In the `config set` command handler, before executing the set operation:
  - Check if the provided key is in the credential keys list
- If it is, display a deprecation warning using `chalk.yellow` that explains
`kdm config setup` is the recommended method and includes the exact command `kdm
config setup` for easy reference
- Still execute the set operation after displaying the warning (soft deprecation
— backward compatibility is preserved)

**Task 2: Update Tests for New Behavior**
- In `src/__tests__/config.test.ts`:
- Add/update tests to verify that a deprecation warning is displayed when
setting any credential key (`notification_service`, `discord_webhook`,
`email_host`, `email_port`, `email_user`, `email_to`) via `config set`
- Add tests to verify that no warning is shown when setting `alert_cooldown` via
`config set`
- Add tests to verify that reconfiguration detection prompts the user when an
existing `notification_service` config exists at the start of `config setup`
- Add tests to verify that credential generation instructions are displayed
before the relevant credential prompts in `config setup`

Research

The KDM CLI is a Kubernetes and Docker monitoring tool built with Commander.js. Commands follow a modular registerXxxCommand(program) pattern in src/commands/. Configuration is managed through src/utils/config.ts using the conf package, with interactive prompts provided by @vr_patel/tui. The existing config setup command already supports Discord, Email, and None notification services with inline validation, while config set accepts any key/value pair without restrictions or guidance.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase enhances `src/commands/config.ts` to make `config setup` a more
complete, guided experience by adding credential generation instructions and
reconfiguration detection.

**Task 1: Add Credential Generation Instructions**
- In `src/commands/config.ts`, before the Discord webhook URL prompt, display
step-by-step instructions using `chalk` for styled output:
- Instructions: Open Discord → Server Settings → Integrations → Webhooks →
Create/Copy URL
- Before the Email SMTP prompts, display SMTP setup instructions using `chalk`:
  - Instructions: guidance on obtaining SMTP credentials from common providers
- Use clear visual separation for instructions (e.g., boxed or indented format)
- Keep instructions concise but actionable, matching the example format in the
ticket

**Task 2: Add Reconfiguration Detection and Confirmation**
- At the start of the `config setup` flow in `src/commands/config.ts`, call
`getConfig()` to check for an existing `notification_service` value
- If a service is already configured:
  - Display the current configuration status to the user
- Prompt the user to confirm reconfiguration using a `select` prompt with Yes/No
options (do not use `confirm` as it is not currently used in the codebase)
  - If the user declines, exit the setup flow without making any changes
- If no existing configuration is found, or if the user confirms, proceed with
the normal setup flow
===============================================================================

Task: 2

This phase updates `src/commands/config.ts` to implement soft deprecation for
credential keys in the `config set` command, and extends
`src/__tests__/config.test.ts` to cover the new behavior.

**Task 1: Define and Enforce Credential Key Restrictions**
- In `src/commands/config.ts`, define a list of credential keys:
`notification_service`, `discord_webhook`, `email_host`, `email_port`,
`email_user`, `email_to`
- Define non-credential keys that remain freely settable without any warning:
`alert_cooldown`
- In the `config set` command handler, before executing the set operation:
  - Check if the provided key is in the credential keys list
- If it is, display a deprecation warning using `chalk.yellow` that explains
`kdm config setup` is the recommended method and includes the exact command `kdm
config setup` for easy reference
- Still execute the set operation after displaying the warning (soft deprecation
— backward compatibility is preserved)

**Task 2: Update Tests for New Behavior**
- In `src/__tests__/config.test.ts`:
- Add/update tests to verify that a deprecation warning is displayed when
setting any credential key (`notification_service`, `discord_webhook`,
`email_host`, `email_port`, `email_user`, `email_to`) via `config set`
- Add tests to verify that no warning is shown when setting `alert_cooldown` via
`config set`
- Add tests to verify that reconfiguration detection prompts the user when an
existing `notification_service` config exists at the start of `config setup`
- Add tests to verify that credential generation instructions are displayed
before the relevant credential prompts in `config setup`

💡 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!