zsh-openshift-aliases — Engineering Report

>_EXECUTIVE SUMMARY

zsh-openshift-aliases is a single-file zsh plugin that registers 52 short aliases over the OpenShift oc CLI, 5 helper functions for replica-stepping and pod lookup, and three login/session shortcuts (ocdev, ocqa, ologin). On source it guards with type -ap -- oc: if no oc executable is on PATH it returns immediately and defines nothing. When oc is present and __start_oc is not already defined it runs source <(oc completion zsh) to wire up native oc tab-completion. The login macros are env-templated — ocdev expands to oc login ${OCP_DEV_URL} -u ${OCP_USERNAME}. Source: 118 zsh lines in one .plugin.zsh file. Pinned by 15 @test blocks across 3 zunit files (230 lines).

oc Aliases

Helper Functions

118

Zsh Lines (plugin entry)

@test Blocks (zunit)

Test Files

230

Test Lines

Load Guard (type -ap oc)

~ARCHITECTURE

One entry file. No autoload tree, no completions/ directory — completion is delegated to oc's own generator. The file is a flat sequence of guard → completion-source → env-var init → alias declarations → fn(){ } definitions.

File / Group	Lines	Role
`zsh-openshift-aliases.plugin.zsh`	118	The whole plugin. Sole entry point.
· load guard	3	`type -ap -- oc` — insists on a real executable on `PATH` (not a shell function); `return 1` if absent, so the plugin no-ops when `oc` is not installed.
· completion source	3	If `__start_oc` is not already defined, `source <(oc completion zsh)` to register `oc` tab-completion once.
· env init + login macros	6	Initializes `OCP_USERNAME` / `OCP_DEV_URL` / `OCP_QA_URL` to empty; declares `ocdev` / `ocqa` (env-templated `oc login`) and `ologin` (`oc rsh`).
· alias declarations	52 total	52 `alias` lines grouped by intent: get (`og`, `opod`, …), describe/deploy/logs (`odesc`, `odep`, `olog`, …), delete (`odel`, `odeldc`, …), export (`oexp`, `opexp`, …), scale (`oscaled`, `ostopd`, …), pod hygiene (`opclean`, `opodr`, `opodt`, `obackup`).
· helper functions	5 fns	`pod` (jsonpath name of a running pod by selector), `oincs` / `oincd` (step a statefulset / dc replicas up by 1), `odecs` / `odecd` (step down by 1). Each reads the current count via `oc get ... -o jsonpath='{.spec.replicas}'` then re-scales.
Total source	118	1 entry file · 52 aliases + 5 functions · pure zsh

Note: 15 of the 52 aliases wrap an inline _(){ … ;};_ positional-argument shim (e.g. opodo, oscaled, the *exp family) so they can take $1 / $@ — zsh aliases cannot otherwise consume positional arguments mid-command.

$ALIAS CONTRACT

Every alias is a thin expansion to an oc invocation. The table is the exact expansion grouped by family. No wrapper logic beyond the inline positional shims.

Family	Aliases	Expansion shape
Login / session	`ocdev` `ocqa` `ologin`	`oc login ${OCP_DEV_URL} -u ${OCP_USERNAME}` / `... ${OCP_QA_URL} ...` / `oc rsh`
Get	`og` `odc` `osts` `ohpa` `opod` `osvc` `opvc` `ois` `obc` `oall` `oalln` `opodo` `opd` `oimg` `olcp` `olp`	`oc get [KIND] [-o wide \| -o jsonpath=... \| -l app=...]`
Describe / deploy / logs / copy	`odesc` `odhist` `odep` `oroll` `orhist` `olog` `osync` `ocp` `ovol`	`oc describe` / `oc apply -f` / `oc rollout {latest,history} dc` / `oc logs -f` / `oc rsync` / `oc cp` / `oc volume dc --all`
Delete	`odel` `odelo` `odela` `odeldc` `odelsts` `odelpod` `odelsvc` `odelbc` `odelpvc`	`oc delete [KIND] [-l app=...]`
Export YAML	`oexp` `opexp` `odexp` `osexp` `ocexp` `ovexp`	`oc get [KIND] $1 -o yaml --export`
Scale	`oscaled` `oscales` `ostopd` `ostartd` `ostarts` `ostops`	`oc scale --replicas=N {dc\|statefulsets}`
Pod hygiene / backup	`opclean` `opodr` `opodt` `obackup`	force-delete `Terminating` pods / jsonpath phase filters / per-object-type YAML dump

=ENVIRONMENT

Three variables drive the login macros. The plugin sets all three to the empty string on source (lines 11–13), so values must be exported after the plugin loads.

Variable	Default	Effect
`OCP_USERNAME`	(empty)	Username passed to `oc login -u` by both `ocdev` and `ocqa`.
`OCP_DEV_URL`	(empty)	Cluster API URL `ocdev` logs into.
`OCP_QA_URL`	(empty)	Cluster API URL `ocqa` logs into.

#TEST COVERAGE

15 @test blocks across 3 zunit files (230 lines). The alias suite stages a fake oc executable on a tmpdir-prefixed PATH so the type -ap -- oc guard passes, then sources the plugin and asserts alias presence and expansion shape. The CI suite runs them under zunit — no live OpenShift cluster required.

File	Tests	Pins
`t-aliases.zsh`	10	Sourcing registers >40 `o` aliases; `ocdev` / `ocqa` reference `OCP__URL` + `OCP_USERNAME` + `oc login`; `ologin` is `oc rsh`; `odel` is `oc delete` (catches name-vs-action drift); `odc` / `obc` are `oc get ... -o wide`; `ocexp` passes `--export`; graceful degradation when `oc` is missing (shell stays alive); re-source idempotency (same alias count).
`t-contract.zsh`	3	Entrypoint stem matches plugin dir basename (accepting the `zsh-` prefix variant); entrypoint parses under `zsh -n`; every `_*` completion file (if any) starts with `#compdef`.
`t-syntax.zsh`	2	`zsh -n` over every `*.zsh` in the plugin directory.
Total	15	3 zunit files · alias-surface + install-contract + syntax

!DESIGN DECISIONS

No-op when oc is absent

The type -ap -- oc guard insists on a real executable on PATH — not a shell function or alias — and return 1s if missing. This lets the plugin be loaded unconditionally in a plugin manager array without a per-host command -v oc wrapper in .zshrc.

Delegate completion to oc

Rather than ship a hand-written _oc compdef, the plugin runs source <(oc completion zsh) — the completion is whatever oc's own generator emits, so it never drifts from the installed oc version. Guarded on __start_oc not already existing to avoid double-sourcing.

Env-templated login macros

ocdev / ocqa are single-quoted aliases that expand ${OCP_DEV_URL} / ${OCP_QA_URL} / ${OCP_USERNAME} at call time, not source time. Change the env vars between invocations and the next ocdev targets the new cluster — no re-source needed.

Inline _(){ } positional shims

Zsh aliases cannot consume positional args mid-command. 15 aliases wrap an inline anonymous-ish _(){ oc ... $1 ... ;};_ function so opodo myapp / oscaled 3 web / ocexp myconfig place the argument where oc needs it instead of appending it at the end.

-o wide on tabular gets

The pod / svc / pvc / dc / sts / is / bc getters default to -o wide so the node, IP, and selector columns oc hides in its narrow default are always shown. One fewer flag to type for the common case.

Replica stepping as functions

oincd / oincs / odecd / odecs need to read the current .spec.replicas before scaling — that round-trip can't be expressed as a static alias, so they are real functions. pod is a function for the same reason: it composes a jsonpath query from a label selector argument.

@FOOTPRINT

Disk: one 118-line .plugin.zsh file plus tests/ (3 files, 230 lines). No completion directory, no autoload tree, no compiled artifacts.
Startup cost: the type -ap oc guard, a one-time source <(oc completion zsh) when oc is present and not yet completed, and 52 alias + 5 function definitions. Zero cost on hosts without oc (early return 1).
Runtime cost: each alias is a direct oc invocation — one subprocess. The replica-stepping functions issue two oc calls (a get to read replicas, a scale to set them).
External tools: oc (required, the load gate); the pod-hygiene / image-tally aliases also shell out to tr, sort, uniq, awk, grep for output post-processing.
Config surface: three OCP_* env vars, all for the login macros. No zstyle, no bindkey, no ZLE widgets.