diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 59ec7f9..a300ee5 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -73,7 +73,6 @@ reviews: instructions: | - Ensure mocks are clean and shared correctly. - Verify that tests cover both happy paths and error conditions. - -pre_merge_checks: - linked_issue_assessment: - mode: "warning" \ No newline at end of file + - pre_merge_checks: + linked_issue_assessment: + mode: "warning" \ No newline at end of file diff --git a/commands.md b/commands.md new file mode 100644 index 0000000..cfa0e2d --- /dev/null +++ b/commands.md @@ -0,0 +1,262 @@ +# KDM CLI Command Reference + +This document provides a comprehensive command reference for the KDM (Kubernetes Docker Monitor) CLI, detailing every command group, subcommand, option flag, and usage example. + +--- + +## 📌 Global Options + +These options apply when invoking the main `kdm` executable: + +| Flag | Description | +|------|-------------| +| `-v, --version` | Output the current version of KDM CLI | +| `-h, --help` | Display general help and command listings | + +--- + +## 1. `kdm show` +Retrieve and display workload resources or cluster metadata in clean, formatted tables. + +### Subcommands: +- **`kdm show runners`** + Displays a combined table of all active Kubernetes pods and Docker containers. +- **`kdm show pods`** + Displays only Kubernetes pods. +- **`kdm show containers`** + Displays only Docker containers. +- **`kdm show nodes`** + Displays details of Kubernetes cluster nodes. +- **`kdm show minikube`** + Checks and prints local Minikube profile and connection status. + +### Examples: +```bash +kdm show runners +kdm show pods +kdm show minikube +``` + +--- + +## 2. `kdm health` +Checks the health of workloads and outputs color-coded logs and details. + +### Options: +- `-w, --watch`: Run in watch mode to continuously refresh the terminal output. +- `-i, --interval `: Refresh interval in seconds (default: `5`). + +### Subcommands: +- **`kdm health all`** + Unified health check of both containers and pods. +- **`kdm health pods`** + Health checks for pods only. +- **`kdm health containers`** + Health checks for Docker containers only. + +### Examples: +```bash +kdm health all +kdm health pods -w # Continuous watch mode (5s refresh) +kdm health containers -w -i 2 # Continuous watch mode (2s refresh) +``` + +--- + +## 3. `kdm watch` +Launches the interactive real-time terminal user interface (TUI) dashboard. Refreshes status and metrics automatically (Ctrl+C to exit). + +### Example: +```bash +kdm watch +``` + +--- + +## 4. `kdm logs ` +Retrieves logs from a workload. KDM attempts a Docker container prefix match first, falling back to Kubernetes pods if no matching container is found. + +### Parameters: +- ``: The container name/ID prefix or the Kubernetes pod name. + +### Example: +```bash +kdm logs auth-api +``` + +--- + +## 5. `kdm analyze` +Scans Kubernetes resources for configuration errors and operational problems. Supports AI-powered troubleshooting explanations. + +### Options: +- `-n, --namespace `: Limit check to a specific Kubernetes namespace. +- `-L, --selector `: Limit check to resources matching a label selector. +- `-f, --filter `: Run a specific analyzer only (e.g. `Pod`, `Ingress`, `Deployment`). Can be specified multiple times. +- `-o, --output `: Output format choice: `text` (default) or `json`. +- `-m, --max-concurrency `: Max concurrency count for analyzers (default: `10`). +- `-s, --with-stat`: Print execution diagnostics statistics. +- `--with-doc`: Retrieve Kubernetes documentation lookups for detected problems. +- `-e, --explain`: Request AI-powered diagnosis explanations. +- `-b, --backend `: Force a specific AI backend provider to query. +- `-l, --language `: Request AI response in a target language (default: `english`). +- `-a, --anonymize`: Mask resource names and identifiers in prompt payload to protect privacy. +- `-c, --no-cache`: Skip looking up or saving to the local AI cache. +- `--kubeconfig `: Specify an alternative kubeconfig file path. +- `--kubecontext `: Specify target Kubernetes context. + +### Examples: +```bash +kdm analyze +kdm analyze -n default --explain +kdm analyze --explain --backend ollama --language spanish +kdm analyze -o json --anonymize +``` + +--- + +## 6. `kdm auth` +Manage credentials, models, and endpoints for AI backend providers. KDM supports **10+** AI providers (OpenAI, Anthropic, Gemini, Vertex AI, WatsonX, OCI GenAI, Cohere, Bedrock, Groq, HuggingFace, etc.). + +### Subcommands: + +- **`kdm auth add`** + Register credentials for a provider. + - Options: + - `-b, --backend `: Target backend name (e.g. `openai`, `ollama`, `anthropic`, `google-gemini`, `google-vertex`, etc.). + - `-m, --model `: Target model name (e.g. `gpt-4o`, `claude-3-5-sonnet-latest`). + - `-p, --password `: API Key or password credential. + - `-u, --baseurl `: Custom API base URL. + - `-t, --temperature `: Model generation temperature. + - `--topp `: Top-P sampling threshold. + - `--topk `: Top-K sampling threshold. + - `--maxtokens `: Max tokens limit. + - `--custom-header `: Add custom HTTP request header. Can be specified multiple times. + +- **`kdm auth list`** + Lists all configured providers and their parameters (API keys are safely masked). + +- **`kdm auth default `** + Sets the active default AI provider. + +- **`kdm auth remove `** + Removes configured settings for a provider. + +- **`kdm auth update `** + Updates settings on an already registered provider (supports the same options as `add`). + +### Examples: +```bash +kdm auth add -b openai -m gpt-4o -p sk-... +kdm auth add -b ollama -m llama3.1 +kdm auth default ollama +kdm auth update ollama -t 0.2 +kdm auth list +``` + +--- + +## 7. `kdm cache` +Manage locally cached AI explanations to save tokens and avoid duplicate network requests. + +### Subcommands: +- **`kdm cache list`** + Lists all cached explanation keys. +- **`kdm cache get `** + Retrieves and prints cached markdown explanation for a key. +- **`kdm cache remove `** + Deletes a specific cache entry. +- **`kdm cache purge`** + Deletes all locally cached explanations. + +### Examples: +```bash +kdm cache list +kdm cache purge +``` + +--- + +## 8. `kdm filters` +Configure default active analyzers to filter what `kdm analyze` checks. + +### Subcommands: +- **`kdm filters list`** + Lists all active default analyzers and available inactive ones. +- **`kdm filters add `** + Adds an analyzer (e.g. `Ingress`, `CronJob`) to default active check list. +- **`kdm filters remove `** + Removes an analyzer from the active list. + +### Examples: +```bash +kdm filters list +kdm filters add Ingress +``` + +--- + +## 9. `kdm custom-analyzer` +Register custom shell commands or HTTP webhooks to analyze arbitrary custom resources (CRDs). + +### Subcommands: + +- **`kdm custom-analyzer add `** + Register a new analyzer. Requires either `--command` or `--url`. + - Options: + - `--command `: External CLI command to execute. + - `--url `: HTTP endpoint URL to call. + +- **`kdm custom-analyzer list`** + Lists all registered custom analyzers. + +- **`kdm custom-analyzer remove `** + Deletes a registered custom analyzer. + +### Examples: +```bash +kdm custom-analyzer add keda --command "kubectl get scaledobjects -A -o json" +kdm custom-analyzer list +kdm custom-analyzer remove keda +``` + +--- + +## 10. `kdm serve` +Starts the KDM server daemon in either REST API mode or JSON-RPC Model Context Protocol (MCP) mode. + +### Options: +- `-p, --port `: HTTP server port (default: `8080`). +- `--metrics-port `: Metrics server port. +- `-b, --backend `: Default active AI backend provider. +- `-f, --filter `: Default analyzer filter limit. +- `--http`: Force HTTP mode (default). +- `--mcp`: Start in MCP mode (JSON-RPC stdio). + +### Examples: +```bash +kdm serve --port 8080 # Starts HTTP REST API on http://localhost:8080 +kdm serve --mcp # Starts JSON-RPC MCP server over stdio +``` + +--- + +## 11. `kdm config` +Interactively set up alerting notifications or directly update config properties. + +### Subcommands: +- **`kdm config setup`** + Launches interactive CLI wizard to configure alerting notifications (Discord Webhook, Email SMTP settings). +- **`kdm config list`** + Lists all general configurations. +- **`kdm config set `** + Manually sets a config parameter. +- **`kdm config clear`** + Resets all configurations to default. + +### Examples: +```bash +kdm config setup +kdm config set alert_cooldown 600 +kdm config list +``` diff --git a/package-lock.json b/package-lock.json index 61df306..7f10e21 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,7 +19,7 @@ "dockerode": "^4.0.0", "ink": "^4.4.1", "nodemailer": "^8.0.7", - "react": "^19.2.6" + "react": "^18.3.1" }, "bin": { "kdm": "bin/kdm.js" @@ -28,7 +28,7 @@ "@types/dockerode": "^3.3.26", "@types/node": "^20.11.24", "@types/nodemailer": "^8.0.0", - "@types/react": "^19.2.15", + "@types/react": "^18.3.0", "@vitest/coverage-v8": "^4.1.7", "tsup": "^8.0.2", "typescript": "^6.0.3", @@ -1620,13 +1620,21 @@ "@types/node": "*" } }, + "node_modules/@types/prop-types": { + "version": "15.7.15", + "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz", + "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==", + "devOptional": true, + "license": "MIT" + }, "node_modules/@types/react": { - "version": "19.2.15", - "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.15.tgz", - "integrity": "sha512-eRwcGNHve+E8qtEQSSRl6urh+rFop4v8gm6O8rGv25CodbvFdLjA1vVQ1KkiFE0w0UPOnb8tDiFKL5lp0rtY5Q==", + "version": "18.3.31", + "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.31.tgz", + "integrity": "sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==", "devOptional": true, "license": "MIT", "dependencies": { + "@types/prop-types": "*", "csstype": "^3.2.2" } }, @@ -4232,10 +4240,13 @@ } }, "node_modules/react": { - "version": "19.2.6", - "resolved": "https://registry.npmjs.org/react/-/react-19.2.6.tgz", - "integrity": "sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q==", + "version": "18.3.1", + "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz", + "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==", "license": "MIT", + "dependencies": { + "loose-envify": "^1.1.0" + }, "engines": { "node": ">=0.10.0" } diff --git a/package.json b/package.json index ed4aab9..1dfb4ce 100644 --- a/package.json +++ b/package.json @@ -47,13 +47,13 @@ "dockerode": "^4.0.0", "ink": "^4.4.1", "nodemailer": "^8.0.7", - "react": "^19.2.6" + "react": "^18.3.1" }, "devDependencies": { "@types/dockerode": "^3.3.26", "@types/node": "^20.11.24", "@types/nodemailer": "^8.0.0", - "@types/react": "^19.2.15", + "@types/react": "^18.3.0", "@vitest/coverage-v8": "^4.1.7", "tsup": "^8.0.2", "typescript": "^6.0.3",