Run Script (scripts/run.sh) Feature Documentation

Overview

This Bash script serves as the entry point for the NoKill K9s plugin. It locates its own directory, optionally activates a Python virtual environment, configures the Python path, and invokes the nokill module. Output is piped through a pager (less) when available, ensuring rich, colorized display in the terminal.

The script streamlines plugin execution whether launched from K9s shortcuts or directly via the command line. By handling environment setup and output formatting, it ensures consistent behavior and readability across different user workflows.

Architecture Overview

flowchart TB
    RS[Run Script] --> AV[Activate Virtualenv]
    AV --> PY[Configure PYTHONPATH]
    PY --> EP[Execute Python Module]
    EP -->|less available| P[Pager - less]
    EP -->|less unavailable| C[Direct Console Output]

Component Structure

1. Environment Initialization

  • Purpose: Determine script location and project root.
  • Key Variables:
Variable Description
SCRIPT_DIR Absolute path to the directory containing this script.
PROJECT_ROOT Parent directory of SCRIPT_DIR, i.e., plugin root.
  • Code Snippet:
  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
  PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"

2. šŸ Virtualenv Activation

  • Purpose: Use the bundled Python environment if present.
  • Behavior:
    • Checks for .venv under PROJECT_ROOT.
    • Sources its activate script to put the venv first in PATH.
  • Code Snippet:
  if [ -d "$PROJECT_ROOT/.venv" ]; then
    # shellcheck disable=SC1091
    source "$PROJECT_ROOT/.venv/bin/activate"
  fi

3. PYTHONPATH Configuration

  • Purpose: Allow importing the nokill package from the project root.
  • Behavior:
    • Prepends PROJECT_ROOT to PYTHONPATH.
    • Respects any existing PYTHONPATH.
  • Code Snippet:
  export PYTHONPATH="$PROJECT_ROOT:${PYTHONPATH:-}"

4. Script Execution & Output Handling

  • Purpose: Run the plugin’s Python module and format its output.
  • Logic:
    1. Detect if less is installed.
    2. If yes, pipe colored, non-wrapped output into less -R -S -K.
    3. Otherwise, print directly to the console.
  • Code Snippet:
  if command -v less >/dev/null 2>&1; then
    python -m nokill "$@" 2>&1 | less -R -S -K
  else
    python -m nokill "$@"
  fi

Sequence Diagram

sequenceDiagram
    participant U as CLI User
    participant S as run.sh
    participant V as Virtualenv
    participant P as Python Module
    participant L as less Pager

    U->>S: invoke scripts/run.sh with args
    S->>V: check for .venv and source if present
    S->>S: set PYTHONPATH to include project root
    S->>P: python -m nokill args
    alt less present
        P-->>L: pipe output (colors, no wrap)
        L-->>U: render paged output
    else less absent
        P-->>U: direct console output
    end

Dependencies

  • Shell: /usr/bin/env bash (POSIX‐compatible)
  • Python: version ≄ 3.10 (as required by nokill)
  • less (optional): for paginated, colorized output

Error Handling

  • set -euo pipefail
    • -e: Exit on any command failure.
    • -u: Treat unset variables as errors.
    • -o pipefail: Pipeline returns first non-zero status.
  • Ensures early exit on configuration or runtime errors.

Usage

  • From K9s: Invoked via plugin shortcuts defined in k9s/plugin.yml.
  • From CLI:
  scripts/run.sh workloads --namespace default

The same script can run any nokill subcommand by passing arguments.

Key Variables Reference

Variable Role
SCRIPT_DIR Location of this script
PROJECT_ROOT Root of the plugin code (parent directory)
PYTHONPATH Ensures nokill package is importable

Testing Considerations

  • With virtualenv: verify .venv/bin/activate exists and is sourced.
  • Without less: confirm output falls back to plain console.
  • Argument forwarding: ensure all CLI args reach python -m nokill.

End of documentation for scripts/run.sh