diff --git a/.github/docs-template/README.md b/.github/docs-template/README.md new file mode 100644 index 0000000..e69de29 diff --git a/.github/docs-template/config/README.md b/.github/docs-template/config/README.md new file mode 100644 index 0000000..18d5ab9 --- /dev/null +++ b/.github/docs-template/config/README.md @@ -0,0 +1,134 @@ +# `kdm config` — Configuration Management + +**Version:** v1.2.1 + +## Overview + +The `kdm config` command group manages KDM CLI configuration, including notification service setup, custom settings, and credential management. Configuration is stored locally using the `conf` package. + +## Syntax + +```bash +kdm config +``` + +## Sub-commands + +### `kdm config setup` + +Interactively sets up the notification service (Discord webhook or Email SMTP). + +**Example:** + +```bash +kdm config setup +``` + +**Interactive Flow:** + +1. Select a notification service: + - **Discord** — Send alerts to a Discord channel via webhook. + - **Email (SMTP)** — Send alerts via email SMTP. + - **None** — Disable notifications. + +2. For **Discord**, you will be prompted for a webhook URL. +3. For **Email**, you will be prompted for SMTP host, port, user, and recipient email. + +**Discord Webhook Setup:** + +1. Open your Discord server settings. +2. Go to **Integrations > Webhooks**. +3. Create a new webhook and choose the alert channel. +4. Copy the webhook URL (must start with `https://discord.com/api/webhooks/`). + +**Email SMTP Setup:** + +| Setting | Default | Description | +|---------|---------|-------------| +| Host | `smtp.gmail.com` | SMTP server address | +| Port | `587` | SMTP port (STARTTLS) | +| User | — | Your email address | +| To | — | Alert recipient email | + +> **Note:** SMTP passwords must be set via the `KDM_SMTP_PASSWORD` environment variable. + +--- + +### `kdm config set ` + +Sets a specific configuration value. + +**Example:** + +```bash +kdm config set alert_cooldown 300 +kdm config set email_port 465 +``` + +**Supported Keys:** + +| Key | Type | Description | +|-----|------|-------------| +| `alert_cooldown` | number | Cooldown period between alerts (seconds) | +| `email_port` | number | SMTP port | +| `notification_service` | string | `discord`, `email`, or `none` | +| `discord_webhook` | string | Discord webhook URL | +| `email_host` | string | SMTP host | +| `email_user` | string | SMTP username | +| `email_to` | string | Alert recipient email | + +--- + +### `kdm config list` + +Lists all current configuration values. + +**Example:** + +```bash +kdm config list +``` + +**Expected Output:** + +``` +Current KDM Configuration: +────────────────────────────────────────────────── + notification_service : discord + discord_webhook : https://discord.com/api/webhooks/... +────────────────────────────────────────────────── + + Note: SMTP passwords must be set via KDM_SMTP_PASSWORD env var. +``` + +--- + +### `kdm config clear` + +Clears all configuration and resets to defaults. + +**Example:** + +```bash +kdm config clear +``` + +**Expected Output:** + +``` +✓ Configuration cleared. +``` + +## Configuration File Location + +Configuration is stored in the default `conf` package location: + +- **macOS:** `~/Library/Application Support/kdm-cli` +- **Linux:** `~/.config/kdm-cli` +- **Windows:** `%APPDATA%\kdm-cli` + +## Common Errors + +- **Invalid webhook URL** — Must match `https://discord.com/api/webhooks//`. +- **Invalid email address** — Must be a valid email format. +- **Invalid port number** — Must be between 1 and 65535. diff --git a/.github/docs-template/health/README.md b/.github/docs-template/health/README.md new file mode 100644 index 0000000..4b26df3 --- /dev/null +++ b/.github/docs-template/health/README.md @@ -0,0 +1,154 @@ +# `kdm health` — Health Status + +> **Version:** `v1.2.1` + +--- + +## Overview + +The `kdm health` command checks and reports the health status of Kubernetes pods or Docker containers. It provides a clean, color-coded table with real-time status fetched directly from Docker and Kubernetes clients. + +> **Fix (Issue #1):** +> This command previously returned only a placeholder message. It now displays real health data from Docker containers and Kubernetes pods. + +--- + +# Syntax + +```bash +kdm health +``` + +--- + +# Parameters + +| Parameter | Description | Valid Values | +| :--- | :--- | :--- | +| `target` | The workload type to check | `pods`, `containers`, `all` | + +--- + +# Usage + +--- + +## `kdm health pods` + +Checks the health status of all Kubernetes pods. + +### Example + +```bash +kdm health pods +``` + +### Expected Output + +```text +╭──────┬─────────────────────────────┬─────────┬──────────────────────────────────────╮ +│ TYPE │ NAME │ HEALTH │ DETAILS │ +├──────┼─────────────────────────────┼─────────┼──────────────────────────────────────┤ +│ pod │ node-app-6f65c56b74-7tkvf │ Running │ namespace: default, restarts: 0 │ +│ pod │ nginx-deployment-abc123 │ Failed │ namespace: production, restarts: 5 │ +╰──────┴─────────────────────────────┴─────────┴──────────────────────────────────────╯ +``` + +### Health Indicators + +| Status Color | Meaning | +| :--- | :--- | +| 🟢 Green | `healthy`, `running`, `Running` | +| 🔴 Red | `unhealthy`, `exited`, `Failed` | +| 🟡 Yellow | Other states like `Pending`, `paused` | + +### Use Cases + +- Monitor pod health in real time +- Identify failing services before outages occur + +--- + +## `kdm health containers` + +Checks the health status of all Docker containers. + +### Example + +```bash +kdm health containers +``` + +### Expected Output + +```text +╭───────────┬────────────┬─────────┬───────────────╮ +│ TYPE │ NAME │ HEALTH │ DETAILS │ +├───────────┼────────────┼─────────┼───────────────┤ +│ container │ test-nginx │ running │ Up 8 minutes │ +│ container │ my-app │ exited │ Exited (1) │ +╰───────────┴────────────┴─────────┴───────────────╯ +``` + +### Use Cases + +- Verify container health +- Detect unhealthy or restarting containers + +--- + +## `kdm health all` + +Checks health for both pods and containers in a single command. If one source (Docker or Kubernetes) is unavailable, the other still renders successfully. + +### Example + +```bash +kdm health all +``` + +--- + +### Expected Output (Kubernetes unavailable) + +```text +⚠ Kubernetes unavailable: connect ECONNREFUSED 127.0.0.1:8080 + +╭───────────┬────────────┬─────────┬──────────────╮ +│ TYPE │ NAME │ HEALTH │ DETAILS │ +├───────────┼────────────┼─────────┼──────────────┤ +│ container │ test-nginx │ running │ Up 8 minutes │ +╰───────────┴────────────┴─────────┴──────────────╯ +``` + +--- + +### Expected Output (Both available) + +```text +╭───────────┬───────────────────────────┬─────────┬──────────────────────────────────────╮ +│ TYPE │ NAME │ HEALTH │ DETAILS │ +├───────────┼───────────────────────────┼─────────┼──────────────────────────────────────┤ +│ container │ test-nginx │ running │ Up 8 minutes │ +│ pod │ node-app-6f65c56b74-7tkvf │ Running │ namespace: default, restarts: 0 │ +╰───────────┴───────────────────────────┴─────────┴──────────────────────────────────────╯ +``` + +--- + +# Common Errors + +| Error | Cause | Fix | +| :--- | :--- | :--- | +| `Unknown target` | Invalid target passed | Use `pods`, `containers`, or `all` | +| `No workloads found` | No containers or pods running | Start Docker containers or Kubernetes pods | +| `Docker unavailable` | Docker daemon not running | Run `sudo systemctl start docker` | +| `Kubernetes unavailable` | No cluster connection | Run `minikube start` or configure `kubectl` | + +--- + +# Notes + +- Supports both Docker and Kubernetes environments +- Displays partial results even if one backend fails +- Provides readable CLI tables for faster debugging and monitoring \ No newline at end of file diff --git a/.github/docs-template/logs/README.md b/.github/docs-template/logs/README.md new file mode 100644 index 0000000..42ace9a --- /dev/null +++ b/.github/docs-template/logs/README.md @@ -0,0 +1,143 @@ +# `kdm logs` — Show Logs + +> **Version:** `v1.2.1` + +--- + +## Overview + +The `kdm logs` command retrieves and displays logs from a specified Docker container or Kubernetes pod. Docker is tried first, and Kubernetes is used automatically as a fallback if no matching container is found. + +> **Fix (Issue #1):** +> This command previously returned only a placeholder message. It now fetches real logs from Docker containers with automatic fallback to Kubernetes pods. + +--- + +# Syntax + +```bash +kdm logs +``` + +--- + +# Parameters + +| Parameter | Description | +| :--- | :--- | +| `name` | Container ID prefix, Docker container name, or Kubernetes pod name | + +--- + +# Usage + +--- + +## `kdm logs ` + +Fetches and displays the last 100 lines of logs for the specified workload. + +--- + +### Example (Docker Container) + +```bash +kdm logs test-nginx +``` + +### Expected Output + +```text +✔ Fetching logs for test-nginx... (0.0s) + +/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration +/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/ +2026/05/17 06:43:38 [notice] 1#1: nginx/1.31.0 +2026/05/17 06:43:38 [notice] 1#1: start worker processes +``` + +--- + +### Example (Kubernetes Pod) + +```bash +kdm logs node-app-6f65c56b74-7tkvf +``` + +### Expected Output + +```text +✔ Fetching logs for node-app-6f65c56b74-7tkvf... (0.0s) + +Server listening on port 3000 +Connected to database +GET /api/health 200 12ms +``` + +--- + +### Example (Container ID Prefix) + +```bash +kdm logs a1b2c3d4 +``` + +--- + +# How It Works + +```text +Docker containers ──► match found? ──► show logs + │ + ▼ no match +Kubernetes pods ──► match found? ──► show logs + │ + ▼ no match +"No container or pod named X found" +``` + +### Workflow + +1. **Docker First** + - Searches running and stopped containers by ID prefix or container name + +2. **Kubernetes Fallback** + - If no Docker match is found, searches all Kubernetes pods across namespaces + +3. **Error Handling** + - Displays an error if neither Docker nor Kubernetes has a matching workload + +--- + +# Finding the Right Name + +```bash +# List Docker containers +docker ps + +# List Kubernetes pods +kubectl get pods --all-namespaces + +# Or use KDM itself +kdm show containers +kdm show pods +``` + +--- + +# Common Errors + +| Error | Cause | Fix | +| :--- | :--- | :--- | +| `No container or pod named X found` | Name does not match any workload | Use `kdm show containers` or `kdm show pods` | +| `Docker unavailable` | Docker daemon is not running | Run `sudo systemctl start docker` | +| `Failed to fetch logs` | Kubernetes API unreachable | Run `minikube start` or configure `kubectl` | + +--- + +# Notes + +- Automatically falls back from Docker to Kubernetes +- Supports container name and ID prefix matching +- Displays real-time logs directly from workloads +- Retrieves the last 100 log lines for faster debugging \ No newline at end of file diff --git a/.github/docs-template/show/README.md b/.github/docs-template/show/README.md new file mode 100644 index 0000000..b11e718 --- /dev/null +++ b/.github/docs-template/show/README.md @@ -0,0 +1,134 @@ +# `kdm show` — Show Running Workloads + +**Version:** v1.2.1 + +## Overview + +The `kdm show` command displays information about running workloads — Docker containers, Kubernetes pods, combined runners, or Minikube status. It provides a unified view of your local development environment. + +## Syntax + +```bash +kdm show +``` + +## Parameters + +| Parameter | Description | Valid Values | +|-----------|-------------|--------------| +| `target` | The workload type to display | `runners`, `pods`, `containers`, `minikube` | + +## Sub-commands + +### `kdm show runners` + +Shows a combined view of all running Docker containers and Kubernetes pods in a single table. + +**Example:** + +```bash +kdm show runners +``` + +**Expected Output:** + +``` +┌───────────┬──────────────┬──────────────────────┬─────────┬─────────────────┐ +│ TYPE │ NAME / ID │ NAMESPACE / IMAGE │ STATUS │ NODE / STATE │ +├───────────┼──────────────┼──────────────────────┼─────────┼─────────────────┤ +│ Pod │ nginx-abc12 │ default │ Running │ minikube │ +│ Container │ my-app │ myregistry/app:v1 │ running │ host │ +└───────────┴──────────────┴──────────────────────┴─────────┴─────────────────┘ +``` + +**Use Cases:** + +- Get a quick overview of all services running locally. +- Monitor both Docker and Kubernetes workloads simultaneously. + +**Common Errors:** + +- `Docker is unreachable` — Docker daemon is not running. Start Docker Desktop or `systemctl start docker`. +- `Kubernetes is unreachable` — No kubeconfig found or cluster is down. Check `kubectl cluster-info`. + +--- + +### `kdm show pods` + +Shows all Kubernetes pods in the current namespace. + +**Example:** + +```bash +kdm show pods +``` + +**Expected Output:** + +``` +┌──────────────┬───────────┬─────────┬──────────┬──────────┐ +│ POD NAME │ NAMESPACE │ STATUS │ RESTARTS │ NODE │ +├──────────────┼───────────┼─────────┼──────────┼──────────┤ +│ nginx-abc12 │ default │ Running │ 0 │ minikube │ +│ redis-xyz34 │ default │ Running │ 2 │ minikube │ +└──────────────┴───────────┴─────────┴──────────┴──────────┘ +``` + +**Use Cases:** + +- Inspect pod status and restart counts. +- Identify pods in non-Running states. + +--- + +### `kdm show containers` + +Shows all running Docker containers. + +**Example:** + +```bash +kdm show containers +``` + +**Expected Output:** + +``` +┌────────────┬────────────┬────────────────┬────────┬─────────┐ +│ CONTAINER │ NAME │ IMAGE │ STATUS │ STATE │ +│ ID │ │ │ │ │ +├────────────┼────────────┼────────────────┼────────┼─────────┤ +│ a1b2c3d4e5 │ my-app │ myregistry/app │ Up │ running │ +└────────────┴────────────┴────────────────┴────────┴─────────┘ +``` + +**Use Cases:** + +- List all active containers. +- Verify container states at a glance. + +--- + +### `kdm show minikube` + +Shows the status of Minikube profiles on the local machine. + +**Example:** + +```bash +kdm show minikube +``` + +**Expected Output:** + +``` +┌─────────┬─────────┬─────────┬─────────────┬─────────┐ +│ NAME │ HOST │ KUBELET │ APISERVER │ MESSAGE │ +├─────────┼─────────┼─────────┼─────────────┼─────────┤ +│ default │ Running │ Running │ Running │ │ +└─────────┴─────────┴─────────┴─────────────┴─────────┘ +``` + +**Common Errors:** + +- `Minikube is not installed on this system` — Install Minikube from https://minikube.sigs.k8s.io. diff --git a/.github/docs-template/watch/README.md b/.github/docs-template/watch/README.md new file mode 100644 index 0000000..66f6a99 --- /dev/null +++ b/.github/docs-template/watch/README.md @@ -0,0 +1,52 @@ +# `kdm watch` — Live Monitoring + +**Version:** v1.2.1 + +## Overview + +The `kdm watch` command enters a live monitoring mode, continuously updating the terminal with real-time resource usage and status of running Docker containers and Kubernetes pods. Powered by Ink for an interactive terminal UI. + +## Syntax + +```bash +kdm watch +``` + +## Parameters + +This command takes no arguments. + +## Usage + +### `kdm watch` + +Starts a real-time monitoring dashboard. + +**Example:** + +```bash +kdm watch +``` + +**Expected Output:** + +The terminal will display an interactive, auto-refreshing table showing: + +- Container/pod names +- Current resource usage (CPU, memory) +- Health status +- Restart counts + +The view updates automatically. Press `Ctrl+C` to exit. + +**Use Cases:** + +- Continuously monitor service health during development. +- Watch for resource spikes or pod restarts in real time. +- Debug intermittent failures by observing live status changes. + +## Common Errors + +- **No workloads found** — Ensure at least one Docker container or Kubernetes pod is running. +- **Docker daemon not running** — Start Docker Desktop or `systemctl start docker`. +- **Kubernetes context not configured** — Verify with `kubectl cluster-info`. diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml new file mode 100644 index 0000000..19f8959 --- /dev/null +++ b/.github/workflows/changelog.yml @@ -0,0 +1,98 @@ +name: Auto Changelog & Versioned Docs + +on: + release: + types: [published] + push: + tags: + - 'v*.*.*' + +jobs: + generate-changelog: + runs-on: ubuntu-latest # Ensure this is here and aligned + + concurrency: + group: auto-changelog-${{ github.ref_name }} + cancel-in-progress: false + + permissions: + contents: write + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: ${{ github.event.repository.default_branch }} + + - name: Build Changelog/Release Notes + id: github_release + uses: mikepenz/release-changelog-builder-action@32e3c96f29a6532607f638797455e9e98cfc703d # v4 + with: + configuration: | + { + "categories": [ + { "title": "### Features", "labels": ["feature", "feat"] }, + { "title": "### Fixes", "labels": ["fix", "bug"] }, + { "title": "### Improvements", "labels": ["perf", "refactor"] }, + { "title": "### Documentation", "labels": ["doc", "docs"] } + ] + } + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Scaffold Versioned CLI Documentation System + env: + CHANGELOG: ${{ steps.github_release.outputs.changelog }} + run: | + VERSION="${{ github.ref_name }}" + TARGET_DIR="docs/${VERSION}" + TEMPLATE_DIR=".github/docs-template" + + # 1. Create the unique versioned directory hierarchy + mkdir -p "$TARGET_DIR" + + # 2. If a core template folder exists, copy its entire structural hierarchy over + if [ -d "$TEMPLATE_DIR" ]; then + shopt -s dotglob nullglob + template_items=("$TEMPLATE_DIR"/*) + if [ ${`#template_items`[@]} -gt 0 ]; then + cp -r "${template_items[@]}" "$TARGET_DIR"/ + fi + # 3. Recursively inject the mandatory Version string into every markdown file copied + find "$TARGET_DIR" -type f -name "*.md" -exec sh -c ' + for file; do + if ! grep -Fq "**Version:** '"$VERSION"'" "$file"; then + printf "\n---\n**Version:** %s\n" "'"$VERSION"'" >> "$file" + fi + done + ' _ {} + + else + # Fallback structure if the template directory isn't initialized yet + mkdir -p "$TARGET_DIR/config" "$TARGET_DIR/health" "$TARGET_DIR/logs" "$TARGET_DIR/show" "$TARGET_DIR/watch" + fi + + # 4. Generate the dedicated version README.md using the Release Engine Changelog output + VERSION_README="$TARGET_DIR/README.md" + echo -e "# KDM CLI Documentation - ${VERSION}\n" > "$VERSION_README" + echo -e "Published on: $(date +'%Y-%m-%d')\n" >> "$VERSION_README" + printf '%s\n' "$CHANGELOG" >> "$VERSION_README" + printf '\n---\n**Version Information:** %s\n' "$VERSION" >> "$VERSION_README" + + - name: Commit and Push Changes + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + + git checkout ${{ github.event.repository.default_branch }} + git pull origin ${{ github.event.repository.default_branch }} --ff-only + + # Track and stage the entire documentation change block + git add docs/ + if git diff --cached --quiet; then + echo "No documentation changes to commit." + exit 0 + fi + + git commit -m "docs: auto-scaffold documentation architecture for ${{ github.ref_name }} [skip ci]" + git push origin HEAD:${{ github.event.repository.default_branch }} diff --git a/README.md b/README.md index d8e5586..2f3a4b7 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,12 @@ KDM (Kubernetes Docker Monitor) is a lightweight, terminal-based monitoring CLI ## Installation +Install kdm-cli via npm: ```bash npm install -g kdm-cli ``` -Or run directly with npx: +Run directly with npx: ```bash npx kdm-cli