// ZSH-SUDO — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zsh-sudo registers one ZLE widget — sudo-command-line — that toggles sudo on the current command line. The widget runs in three modes: (1) BUFFER empty → pull the previous command via builtin fc -ln -1 and prepend; (2) BUFFER already starts with sudo (after any leading whitespace, var-assignments, builtin/command/env wrappers, and stacked sudo flags) → strip the whole prefix; (3) otherwise → prepend $ZPWR_SUDO_CMD. The matching is two parallel regex patterns: one against $LBUFFER (cursor at or after sudo), one against $RBUFFER (cursor before sudo) — so the toggle works regardless of where the user's cursor sits on a long line. Both the command word and the regex are environment-configurable so the same widget works for doas, please, run0, or any other privilege-escalation tool.

#FILE STRUCTURE

No autoload/, no src/, no completions/ directory. The whole plugin is one file. The keybinding itself is intentionally not set by the plugin — the README documents the canonical pattern (bindkey '^N' sudo-command-line) but leaves the user to choose their chord. The widely-published "Esc Esc" binding in oh-my-zsh's stock sudo plugin is one of many valid choices; this plugin doesn't force one.

$ENV CONTRACT

Two env vars, both only set when unset. The user controls the strip-and-prepend tool by exporting these before sourcing the plugin.

Both vars are guarded by (( $+ZPWR_SUDO_CMD )) / (( $+ZPWR_SUDO_REGEX )), so re-sourcing the plugin won't clobber a user override and the unset path is the only path that writes a default.

@WIDGET FLOW

Single fn, three branches. Order is fixed: empty-BUFFER recall first, then LBUFFER strip attempt, then RBUFFER strip attempt, then unconditional prepend. The LBUFFER/RBUFFER split is the load-bearing trick — it preserves cursor position on long lines.

  ^X invoked (any keybinding chosen by user)
       │
       ▼
  ┌──────────────────────────────────────┐
  │ BUFFER empty?                        │
  │   yes → LBUFFER = "$(fc -ln -1)"     │ ← pull last cmd from history
  │   no  → leave BUFFER as-is           │
  └────────────────┬─────────────────────┘
                   │
                   ▼
  ┌──────────────────────────────────────┐
  │ LBUFFER matches sudo-prefix regex?   │
  │   yes → LBUFFER = "$match[1]$match[-1]"  │ ← strip whole prefix
  │   no  → fallthrough                  │     keep leading whitespace
  └────────────────┬─────────────────────┘     + post-sudo command
                   │
                   ▼ (no LBUFFER match)
  ┌──────────────────────────────────────┐
  │ RBUFFER matches sudo-prefix regex?   │
  │   yes → RBUFFER = "$match[1]$match[-1]"  │
  │   no  → fallthrough                  │
  └────────────────┬─────────────────────┘
                   │
                   ▼ (neither side matched)
  ┌──────────────────────────────────────┐
  │ LBUFFER = "$ZPWR_SUDO_CMD $LBUFFER"  │ ← unconditional prepend
  └──────────────────────────────────────┘

The cursor doesn't move on toggle — $LBUFFER and $RBUFFER are zsh's split of the command line at the cursor position, so editing the side the cursor isn't on preserves the cursor's column. This is what makes the widget feel like a true toggle: hit the chord twice and you're back where you started, character-for-character.

&REGEX ANATOMY

One regex pattern, applied twice (LBUFFER + RBUFFER). It's a 700-character beast covering 8 grammar classes of "this counts as a sudo invocation." Each class below is a section of the pattern; the strip path drops everything matched and leaves $match[1] (leading whitespace) + $match[-1] (the trailing command and its args).

The regex requires (...)+ on the sudo block so at least one sudo invocation must match for the strip path to fire. This is why the toggle never false-positive-strips a non-sudo command, even one that happens to contain literal whitespace and var-assignments.

// SUDO FLAGS COVERED

~EXAMPLE TRANSFORMS

Toggle behaviour across the cases the regex is built to cover. Each row is one widget invocation, before → after.

!LBUFFER VS RBUFFER

ZLE splits the command line at the cursor: text to the left is in $LBUFFER, text to the right is in $RBUFFER. The widget runs the strip regex against $LBUFFER first, then falls through to $RBUFFER on no match. Toggling works at any cursor position.

*TEST COVERAGE

101 zunit @test cases across 6 test files. The heaviest is t-sudo-command-line.zsh at 81 cases — every regex branch is pinned by at least one before/after pair plus a no-op pair (calling the widget twice should round-trip). The remaining 5 files pin structural contracts: widget registration, env-var defaults, idempotent re-source, entrypoint stem, syntax cleanliness.

?KEY DESIGN DECISIONS

Each call-out is a decision the implementation could have gone either way on, with the rationale for the path taken.

.STRATEGIC POSITION

Smallest plugin in the stack by LOC, and arguably the highest invocations-per-day. Privilege escalation comes up dozens of times in a sysadmin shell session; a one-chord toggle saves the entire "up-arrow, home, type sudo space, end, enter" dance every single time.

+COMPAT

Hard deps: zsh 5.x+ with ZLE; no external tool deps — the widget runs entirely within zsh's match engine. builtin fc is a core zsh builtin, always available. Compat with doas, please, run0, pkexec, or any other prepend-style escalation tool by setting ZPWR_SUDO_CMD + ZPWR_SUDO_REGEX. No OS-specific behaviour — identical on macOS, Linux, BSD, WSL.