// ZSH-SED-SUB — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zsh-sed-sub adds one ZLE widget — basicSedSub — bound to Ctrl-F Ctrl-P across all three default zsh keymaps (viins / vicmd / emacs). When invoked, the widget reads a before>after sed expression a single keystroke at a time via read -k, paints the prompt-line buffer in ANSI cyan/magenta to indicate edit state, and on Enter rewrites the entire $BUFFER via sed -E "s@before@after@g". Backspace deletes one char, Ctrl-U clears the input, ESC aborts. The widget is the canonical "fix the typo in this long command line" tool — the same intent as Emacs query-replace, but at the zsh command-line layer rather than the editor layer. 74 LOC of autoload code, 12 LOC of entrypoint, 44 zunit @test cases across 6 files pinning the keybinding, widget registration, the auto-up trigger on empty BUFFER, and the entire interactive flow.

#FILE STRUCTURE

@WIDGET FLOW

The widget body is a single read loop with three exit conditions: Enter (commit), ESC (abort), >-missing on Enter (error and abort). On commit it rewrites the entire $BUFFER via a sed subshell. State lives in three locals: sedArg (the accumulating before>after string), orig (split ${sedArg%%>*}), replace (split ${sedArg##*>}).

  ^F^P pressed (any keymap)
       │
       ▼
  ┌────────────────────────────────────┐
  │ emulate -LR zsh                    │ ← local-scope zsh emulation,
  │                                    │   no interference from
  │                                    │   user's setopt
  └────────────┬───────────────────────┘
               │
               ▼
  ┌────────────────────────────────────┐
  │ BUFFER empty / whitespace-only?    │
  └────────────┬───────────────────────┘
       │ yes                    │ no
       ▼                        │
  zle up-line-or-history        │
  (pull last command for edit)  │
       │                        │
       └────────────┬───────────┘
                    ▼
  ┌────────────────────────────────────┐
  │ paint "Zsh-BsS: ..." status banner │ ← \x1b[1;34m underline
  │ enter colored read mode            │   \x1b[1;44;37m bg-blue
  └────────────┬───────────────────────┘
               │
               ▼
  ┌────────────────────────────────────┐
  │ LOOP:  read -k key                 │
  │   key == \n / \r?  → break (commit)│
  │   key == ESC?      → return 1      │
  │   key == \x7f|^h?  → backspace     │
  │   key == ^U?       → clear sedArg  │
  │   key == '>'?      → flip color    │
  │   else             → append to sedArg │
  │   zle -R "...: $sedArg"            │ ← live preview redraw
  └────────────┬───────────────────────┘
               │
               ▼ (commit)
  ┌────────────────────────────────────┐
  │ sedArg contains '>'?               │
  │   no  → "Needed '>'" error, abort  │
  │   yes → split on > into orig, replace │
  └────────────┬───────────────────────┘
               │
               ▼
  ┌────────────────────────────────────┐
  │ Escape '@' in orig + replace       │ ← so we can use @ as
  │ sedArg = "s@$orig@$replace@g"      │   the sed delimiter
  └────────────┬───────────────────────┘
               │
               ▼
  ┌────────────────────────────────────┐
  │ BUFFER contains orig?              │
  │   no  → "No Match." error, abort   │
  └────────────┬───────────────────────┘
               │ yes
               ▼
  ┌────────────────────────────────────┐
  │ BUFFER = print -r -- $BUFFER |     │
  │            sed -E -- "$sedArg"     │
  └────────────────────────────────────┘

$KEYSTROKE TABLE

Inside the read loop, the widget interprets six specific keystrokes; every other byte is appended to the accumulating sedArg buffer.

// CHARACTER COMPARISON IDIOM

All key tests use zsh's numeric-character syntax: (( (#key) == (##\n) )), (( (#key) == (##\e) )), (( (#key) == (##^U) )). $((#x)) evaluates to the code point of the first character of $x; $((##c)) evaluates to the code point of the literal character c in the source. The pattern is the canonical zsh way to write keystroke matches without string-quoting the control character.

&DELIMITER STRATEGY

The widget uses > as the user-facing delimiter between the search and replace halves — that's why the syntax is orig>replace, not orig/replace. Internally, the sed expression uses @ as its delimiter because @ is rare in command-line contexts. The widget escapes any literal @ in either half before assembling the final s@orig@replace@g expression.

~STATE MACHINE

The widget runs a 3-colour ANSI state machine on the prompt line. The colour conveys which phase the user is in, with zero help text required.

!KEYBINDING SURFACE

One chord, three keymaps. The plugin runs bindkey -M viins '^F^P' basicSedSub, then again for vicmd, then again for emacs. The user's bindkey -v / bindkey -e choice doesn't matter; the keybinding fires from every default keymap.

The chord ^F^P was chosen because neither ^F nor ^P alone is rebound to basicSedSub; each remains free for their default ZLE actions (forward-char, up-line-or-history). The widget itself uses zle up-line-or-history to pre-load the previous command into $BUFFER when invoked on an empty prompt — an inline mirror of ^P's default behaviour.

*TEST COVERAGE

44 zunit @test cases across 6 test files. t-plugin.zsh is the heaviest at 23 cases — it spawns a sub-shell, sources the plugin, drives the widget with stubbed read input, and asserts the resulting $BUFFER. The other files pin structural contracts: keybinding presence in all 3 keymaps, widget registration, autoload coverage, syntax cleanliness, and the entrypoint stem.

?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

The smallest meaningful widget in the MenkeTechnologies plugin stack — 86 LOC for a single-chord command-line transform. It's the canonical example of "zsh extensibility lets you carve out a specific friction point and obliterate it." Adjacent plugins in the stack (zsh-sudo, zsh-git-acp, zsh-expand) follow the same shape: one chord, one fn, one BUFFER rewrite.

+LOAD MODEL

The plugin's source-time work is: 1 fpath append, 1 autoload -Uz, 1 zle -N, 3 bindkey -M calls. Total work: well under a millisecond on any zsh. The widget body itself doesn't run until the user actually presses ^F^P.

^COMPAT

Hard deps: zsh (with ZLE; the widget assumes interactive zsh), sed (BSD or GNU; the -E flag is portable across both). No optional deps. Compat floor is zsh 5.x — no zsh 6 features. The widget uses zsh's numeric-character syntax ($((#x))) which has been stable since the 4.x line.

If ^F^P conflicts with the user's existing keybindings, they can rebind: bindkey -r '^F^P' followed by a custom bindkey '...' basicSedSub. The widget name doesn't move; only the chord does.