feat(kube-ps1): add kube-ps1 plugin

[rafacouto]

Closes #719

Description

Adds a new kube-ps1 plugin that displays the current Kubernetes context and
namespace in the shell prompt, with kubeon / kubeoff commands to toggle it
interactively.

Changes

• plugins/kube-ps1/kube-ps1.plugin.sh — main plugin
• plugins/kube-ps1/README.md — documentation and configuration reference
• plugins/kube-ps1/LICENSE — Apache 2.0 license from the upstream project (required by its license terms)
• plugins/README.md — added kube-ps1 entry to the plugin table

Implementation details

• Internal functions and variables follow the _omb_plugin_kube_ps1_* naming convention.
• Uses _omb_util_add_prompt_command() and _omb_util_command_exists() from the OMB API.
• The kube_ps1 segment is injected into PS1 via a lazy-registered post-theme hook, so it works correctly regardless of which theme is active — no theme modifications required.
• The kubeconfig files are watched for changes; context/namespace are only re-fetched when a file is actually modified, keeping prompt overhead minimal.
• kubeon -g / kubeoff -g persist the state across sessions via ~/.kube/kube-ps1/disabled.

Usage

# ~/.bashrc
plugins=(... kube-ps1)

[qodo-free-for-open-source-projects]

Review Summary by Qodo

Add kube-ps1 plugin for Kubernetes prompt integration

✨ Enhancement

Walkthroughs

Description

• Adds new kube-ps1 plugin displaying Kubernetes context and namespace
• Implements kubeon/kubeoff commands for interactive toggling
• Includes efficient kubeconfig file watching to minimize prompt overhead
• Supports persistent global state via ~/.kube/kube-ps1/disabled marker

Diagram

flowchart LR
  A["kube-ps1 Plugin"] --> B["kube_ps1 Function"]
  A --> C["kubeon/kubeoff Commands"]
  A --> D["PROMPT_COMMAND Hook"]
  B --> E["Display Context & Namespace"]
  C --> F["Toggle On/Off"]
  D --> G["Watch kubeconfig Files"]
  G --> H["Update Prompt Segment"]
  F --> I["Persist State Globally"]

Loading

File Changes

1. plugins/kube-ps1/kube-ps1.plugin.sh ✨ Enhancement +422/-0

Core kube-ps1 plugin implementation

• Main plugin implementation with 422 lines of bash code
• Provides kube_ps1() function to display Kubernetes context and namespace in prompt
• Implements kubeon and kubeoff commands with session and global toggle support
• Includes PROMPT_COMMAND hook for efficient kubeconfig file watching and context/namespace updates
• Supports extensive customization via KUBE_PS1_* configuration variables for colors, symbols, and
 formatting

plugins/kube-ps1/kube-ps1.plugin.sh

---

2. plugins/kube-ps1/README.md 📝 Documentation +114/-0

Plugin documentation and configuration guide

• Comprehensive documentation for the kube-ps1 plugin
• Includes requirements, installation, and usage instructions
• Documents all configuration variables for display, colors, and custom functions
• Provides example configurations and command reference
• Explains licensing and attribution to original kube-ps1 project

plugins/kube-ps1/README.md

---

3. plugins/kube-ps1/LICENSE 📝 Documentation +179/-0

Apache 2.0 license for kube-ps1

• Apache License 2.0 full text (179 lines)
• Required by upstream kube-ps1 project license terms
• Covers derivative work adaptation for Oh My Bash

plugins/kube-ps1/LICENSE

---

View more (1)

4. plugins/README.md 📝 Documentation +1/-0

Register kube-ps1 in plugins index

• Added kube-ps1 entry to the plugins table
• Links to kube-ps1 plugin directory with brief description
• Maintains alphabetical ordering in plugin list

plugins/README.md

---

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (3) 📎 Requirement gaps (1)

1. split_config expands globs ☑ 📘 Rule violation ⛨ Security

Description

_omb_plugin_kube_ps1_split_config prints an unquoted $2, which can trigger pathname expansion
when KUBECONFIG contains glob characters and can mis-handle config paths. This is unsafe handling
of external input and can lead to incorrect config-file detection.

Code

plugins/kube-ps1/kube-ps1.plugin.sh[R169-172]

+_omb_plugin_kube_ps1_split_config() {
+  local IFS="$1"
+  # word-split on IFS
+  printf '%s\n' $2

Evidence

Compliance requires validating/sanitizing external inputs; here KUBECONFIG is consumed via
unquoted expansion, enabling unintended glob expansion and unreliable parsing.

Rule 6: Generic: Security-First Input Validation and Data Handling
plugins/kube-ps1/kube-ps1.plugin.sh[169-172]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`_omb_plugin_kube_ps1_split_config` uses an unquoted `$2`, which can cause pathname expansion (globbing) and incorrect parsing of `KUBECONFIG`.
## Issue Context
`KUBECONFIG` is an external input (env var) and may include characters like `*` or `?`. In bash, unquoted expansions trigger pathname expansion unless disabled.
## Fix Focus Areas
- plugins/kube-ps1/kube-ps1.plugin.sh[169-173]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. README prompt setup conflicts ☑ 📎 Requirement gap ✓ Correctness

Description

The README instructs users to add $(kube_ps1) to PS1, but the plugin also auto-injects the kube
segment into PS1 via a prompt hook, which can cause duplicated segments and prompt conflicts. This
is misleading documentation and can break expected prompt behavior for users following the
instructions.

Code

plugins/kube-ps1/README.md[R37-45]

+## Add to your prompt
+
+The plugin exposes a `kube_ps1` function that outputs the formatted context
+string.  Add it to your `PS1` (or to your theme's
+`_omb_theme_PROMPT_COMMAND`):
+
+```bash
+PS1='[\u@\h \W $(kube_ps1)]\$ '
+```

Evidence

Compliance requires documentation to accurately describe enablement and theme/prompt integration;
the README's manual PS1 guidance conflicts with the plugin's automatic PS1 injection behavior.

Documentation added for kube-ps1 plugin usage and configuration
Respect existing Oh-My-Bash configuration and avoid prompt conflicts
plugins/kube-ps1/README.md[37-45]
plugins/kube-ps1/kube-ps1.plugin.sh[233-240]
plugins/kube-ps1/kube-ps1.plugin.sh[245-253]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The README tells users to manually add `$(kube_ps1)` to `PS1`, but the plugin already injects kube-ps1 output into `PS1` automatically, which can result in duplicated prompt segments.
## Issue Context
Users following the README will likely get two kube-ps1 segments (one from their `PS1` and one from the plugin hook), violating the goal of conflict-free prompt integration.
## Fix Focus Areas
- plugins/kube-ps1/README.md[37-45]
- plugins/kube-ps1/kube-ps1.plugin.sh[233-253]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. stat errors leak to prompt ☑ 📘 Rule violation ⛯ Reliability

Description

_omb_plugin_kube_ps1_file_newer_than does not suppress or handle stat failures, which can print
errors (including local paths) during prompt rendering if a kubeconfig file disappears or becomes
inaccessible. This is not graceful degradation for an expected edge case in a prompt hook.

Code

plugins/kube-ps1/kube-ps1.plugin.sh[R175-184]

+_omb_plugin_kube_ps1_file_newer_than() {
+  local file="$1" check_time="$2" mtime
+  if stat -c "%s" /dev/null &>/dev/null; then
+    # GNU stat
+    mtime=$(stat -L -c %Y "${file}")
+  else
+    # BSD stat (macOS)
+    mtime=$(stat -L -f %m "${file}")
+  fi
+  (( mtime > check_time ))

Evidence

Compliance requires robust handling of failure points; calling stat without error handling in a
prompt hook can surface noisy errors and degrade the prompt experience.

Rule 3: Generic: Robust Error Handling and Edge Case Management
plugins/kube-ps1/kube-ps1.plugin.sh[175-184]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`stat` failures can print errors during prompt rendering because the output/error is not suppressed and failures are not handled.
## Issue Context
This function is executed from a `PROMPT_COMMAND` hook, so any stderr output becomes user-visible and noisy.
## Fix Focus Areas
- plugins/kube-ps1/kube-ps1.plugin.sh[175-185]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. kubeoff -g ignores failures ☑ 📘 Rule violation ⛯ Reliability

Description

Global enable/disable operations (mkdir, touch, rm) are not checked for failure, so `kubeoff
-g/kubeon -g` may report success via state changes even when persistence cannot be written. This
can leave users in a confusing state across sessions.

Code

plugins/kube-ps1/kube-ps1.plugin.sh[R324-347]

+kubeon() {
+  case "${1:-}" in
+    -h|--help)
+      _omb_plugin_kube_ps1_kubeon_usage ;;
+    -g|--global)
+      rm -f -- "${_omb_plugin_kube_ps1_disable_path}"
+      KUBE_PS1_ENABLED=on ;;
+    "")
+      KUBE_PS1_ENABLED=on ;;
+    *)
+      printf 'error: unrecognized flag %s\n\n' "${1}" >&2
+      _omb_plugin_kube_ps1_kubeon_usage
+      return 1 ;;
+  esac
+}
+
+kubeoff() {
+  case "${1:-}" in
+    -h|--help)
+      _omb_plugin_kube_ps1_kubeoff_usage ;;
+    -g|--global)
+      mkdir -p -- "$(dirname "${_omb_plugin_kube_ps1_disable_path}")"
+      touch -- "${_omb_plugin_kube_ps1_disable_path}"
+      KUBE_PS1_ENABLED=off ;;

Evidence

Compliance requires identifying and handling failure points; these filesystem writes are external
side effects and should be validated with actionable error reporting when they fail.

Rule 3: Generic: Robust Error Handling and Edge Case Management
plugins/kube-ps1/kube-ps1.plugin.sh[324-347]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Global persistence operations for `kubeon -g` / `kubeoff -g` do not handle filesystem errors, which can lead to inconsistent state.
## Issue Context
These commands are user-facing toggles; they should fail loudly and predictably when persistence cannot be applied.
## Fix Focus Areas
- plugins/kube-ps1/kube-ps1.plugin.sh[324-347]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Malformed k8s symbol ☑ 🐞 Bug ✓ Correctness

Description

The k8s custom symbol uses $'\Uf10fe', but \U escapes require 8 hex digits; the prompt symbol
will not render as intended when KUBE_PS1_SYMBOL_CUSTOM=k8s.

Code

plugins/kube-ps1/kube-ps1.plugin.sh[R143-145]

+    k8s)
+      symbol="$(_omb_plugin_kube_ps1_color_fg "${KUBE_PS1_SYMBOL_COLOR}")$'\Uf10fe'${reset_color}"
+      ;;

Evidence

The k8s branch uses an ANSI-C quoted Unicode escape with an invalid \U length; elsewhere the
script uses a valid \u escape for a BMP character, highlighting the inconsistency.

plugins/kube-ps1/kube-ps1.plugin.sh[139-155]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The custom symbol branch `k8s)` uses `$'\Uf10fe'`, which is a malformed `\U` Unicode escape (should be 8 hex digits). This causes the symbol to render incorrectly or literally.
### Issue Context
Other branches use valid `$'\u....'` sequences or raw UTF-8 byte sequences for compatibility.
### Fix Focus Areas
- plugins/kube-ps1/kube-ps1.plugin.sh[139-155]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Kube segment delayed ☑ 🐞 Bug ⛯ Reliability

Description

Because ps1_append is registered lazily inside the prompt hook, it won’t run until the next
prompt-render cycle; the first prompt after shell startup typically won’t show the kube segment.

Code

plugins/kube-ps1/kube-ps1.plugin.sh[R248-253]

+  # Lazy first-run: register ps1_append AFTER the theme has been added to
+  # _omb_util_prompt_command, so it always executes last.
+  if [[ "${_omb_plugin_kube_ps1_initialized}" == false ]]; then
+    _omb_plugin_kube_ps1_initialized=true
+    _omb_util_add_prompt_command _omb_plugin_kube_ps1_ps1_append
+  fi

Evidence

OMB’s prompt hook iterates over an array expanded at loop start, so adding a new hook mid-iteration
doesn’t execute it in the current prompt cycle. Since plugins load before themes, the first prompt
run registers ps1_append for subsequent prompts.

plugins/kube-ps1/kube-ps1.plugin.sh[248-253]
lib/utils.sh[349-354]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`ps1_append` is added during the first execution of `prompt_update`, so it cannot run in that same prompt-render cycle due to array expansion semantics.
### Issue Context
Plugins are loaded before themes in OMB init, so `prompt_update` typically runs before the theme on the first prompt.
### Fix Focus Areas
- plugins/kube-ps1/kube-ps1.plugin.sh[248-253]
- lib/utils.sh[349-354]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[brbecker]

@rafacouto Thank you for this. I was just considering how I would do this myself.

A few things:

1. I'd like to have the context on a separate line, so I set KUBE_PS1_SUFFIX to ')\n', which works, but because of line 249, a space is inserted automatically before the rest of the prompt.
2. Issue number 6 noted by qodo is mildly annoying. Would like to see it fixed.
3. What exactly is KUBE_PS1_HIDE_IF_NOCONTEXT supposed to do when set to false? I would expect it to indicate something like NONE or N/A for the cluster and namespace if there is no active context. Instead, nothing at all appears, which seems to be exactly what KUBE_PS1_HIDE_IF_NOCONTEXT should do when true.
4. I chose to install it in .oh-my-bash/custom/plugins for testing to keep it out if the main OMB code.

[rafacouto]

Thanks @brbecker for the review.

1. fixed: e86438e
2. fixed: 8395eeb
3. fixed: 1f3315f
4. good idea