>_EXECUTIVE SUMMARY
ZPWR is a heavily-instrumented terminal operating environment for zsh: a curated autoload tree, a zinit-managed plugin stack, an interactive tmux cockpit, a unified zpwr <verb> dispatcher, and a self-installing toolchain that pulls down hundreds of CLI utilities on macOS and Linux. The project began as a fork of Hashrocket's Dotmatrix in 2017 and has grown into a single-user cyberdeck: 1,277 tracked files, ~107k zsh+sh lines, 533 autoload functions, 462 verb keys (460 unique spellings) mapping to 372 distinct zpwr functions, 228 zsh keybindings, 80 tmux bindings, 48 zinit plugins, 654 brew formulas/casks installed, 149 test files / 79k lines of zunit (14,277 @test cases), 217 wizard encyclopedia pages, 39 screenshots, 6,309 commits across 617 tags spanning ~9 years — built almost entirely by one engineer (11,358 of 11,360 commits across all branches; the other 2 are from early collaborator MichaelDimmitt).
Source Distribution — 107,352 zsh+sh lines
Counted from 383 tracked .zsh files and 175 .sh files (git ls-files, excluding .git/). Side scripts add .vim (4 files, 4,748 lines), .py (3 files, 2,618 lines), .pl (7 files, 458 lines), .stk (8 files, 235 lines), .js (1 file, 304 lines).
~REPO MAP
Top-level partition of ~/.zpwr/. Numbers are tracked-file counts and raw line counts (wc -l) at the time this report was generated. local/ dominates by line count because it holds runtime caches, snapshots, and the encyclopedia output — the part of the tree that grows on every shell start, not the source.
| Directory | Files | Lines | Role |
|---|---|---|---|
| autoload/ | 533 | 22,464 | Per-function autoload tree. fpath-loaded on shell start. 470 in common/, 21 in fzf/, 15 in comps/, 12 in comp_utils/, 6 in darwin/, 5 in linux/, 4 in systemctl/. |
| env/ | 9 | 3,401 | Environment, exported vars, p10k config, verb dispatch table (zpwr.zsh — 553 lines, 462 verb keys). Counts tracked files; .zwc bytecode shadows are generated, not committed. |
| install/ | 107 | 82,152 | One-shot installers: 25 shell scripts, package manifests, casks.sh/formulae.sh with 654 brew formulas/casks, vim/nvim configs, JetBrains/iTerm/Alacritty configs, systemd units. |
| local/ | 241 | 5,512,872 | Runtime cache: .cache/completions, git-repo dirty/clean caches, alias caches, zcompdump, generated keybindings, snapshot tarballs. Regenerated by zpwr regen verbs. |
| man/ | 2 | 2,907 | man1/zpwr.1 (8 KB, top-level man page) + man1/zpwrall.1 (53 KB, comprehensive meta page covering every verb and option). |
| scripts/ | 179 | 17,579 | Standalone CLI utilities not autoloaded as functions, across scripts/ root and subdirs. Range from one-off shell wrappers to long-running monitors. |
| tests/ | 150 | 79,650 | 149 zunit test files (one _support/testfile fixture). Probes every autoload function, env var, syntax check, and behavioral contract — 14,277 @test cases in total. |
| tmux/ | 24 | 883 | tmux configurations: per-version (tmux_lt_21, tmux_ge_21, ..., tmux_ge_31), per-OS (tmux-mac, tmux-linux, tmux-wsl), and pane layouts (four-panes, eight-panes, sixteen-panes, thirtytwo-panes, REPL variants). |
| docs/ | 262 | 39,699 | HTML encyclopedia (index.html), CSS theme (hud-static.css, tutorial.css), hud-theme.js, this engineering report (report.html), 39 screenshots, 217 wizard_pages/page_NNN.zsh source pages. |
| TOTAL (tracked) | 1,277 | ~248k | Tracked source files via git ls-files; local/ line totals above are an on-disk runtime snapshot, not committed. |
#AUTOLOAD TREE
autoload/ is the heart of ZPWR. Every entry in this tree is one function file, picked up by zsh's autoload -Uz mechanism the first time it's called — so a fresh shell pays no cost for functions it never uses. 533 files across 7 subdirectories partitioned by platform (darwin/, linux/, systemctl/), tooling (fzf/, comps/, comp_utils/), and the catch-all common/ (87% of all autoloads).
| Subdirectory | Files | Lines | Description |
|---|---|---|---|
| autoload/common/ | 470 | 18,564 | The verb implementations themselves — 372 distinct zpwr* functions plus short-name helpers (z, zal, zhc, cv, ...). Mostly one function per file at ~40 lines each. |
| autoload/fzf/ | 21 | 249 | fzf completion shims: _fzf_complete_zpwr, _fzf_complete_git, _fzf_complete_vim, plus post-processors (___fzf_complete_*_post). |
| autoload/comps/ | 15 | 730 | zsh completion functions (_zpwr — 405 lines — _zcommand, _p, _r, _f, _digs). Drive Tab-completion for ZPWR verbs and shortened aliases. |
| autoload/comp_utils/ | 12 | 447 | Helpers consumed by the completion functions: _files, _parameters, _megacomplete, _complete_hist, _complete_clipboard, fasd dir/file expanders. |
| autoload/darwin/ | 6 | 92 | macOS-only: zpwrDarwinBanner, zpwrScriptToPDF (uses cupsfilter), nn (Notes.app helper), db/db2 (Docker bridge), exe (open via Finder). |
| autoload/linux/ | 5 | 177 | Linux-only: zpwrLinuxBanner, zpwrLinuxPlugins, zpwrAttachSetup, tailufw, scriptToPDF. |
| autoload/systemctl/ | 4 | 112 | systemd helpers: ssu/ssd (start/stop), restart, restartZabbixAgent. Only fpath'd on Linux hosts. |
| TOTAL | 533 | 20,371 | +5 .zwc compiled bytecode shadows in common/ for hot-loaded functions. |
// FUNCTION CATEGORIES (autoload/common)
Diagnostics
zpwrDoctor, zpwrLint, zpwrBench, zpwrTop, zpwrFlame, zpwrStartup, zpwrTrace, zpwrDeps, zpwrPathaudit, zpwrStale, zpwrPorts, zpwrSnapshot, zpwrRestore.
Editor Bridges
zpwrEditor, zpwrEditorRecent, zpwrVimAll, zpwrVimFzf, zpwrVimRecent, zpwrEmacsAll, zpwrEmacsScripts, zpwrSudoVimRecent + nvim/emacs/vim variants for every flow.
fzf Pickers
zpwrFzfFilesearch*, zpwrFzfDirsearch*, zpwrFzfWordsearch*, zpwrFzfEnv, zpwrFzfCommits, zpwrFzfZshKeybind, zpwrFzfVimKeybind, zpwrFzfAllKeybind, zpwrIntoFzf, zpwrAgIntoFzf.
Git
zpwrCommits, zpwrAllRemotes, zpwrAllUpdates, zpwrChangeGitEmail, zpwrChangeGitAuthorEmail, zpwrClearGitFile, zpwrCleanGitRepoCache, zpwrCleanGitRepoDirtyCache, zpwrLargestGitFiles, zpwrGitwho, zpwrGitCheckoutRebasePush.
Cache / Regen
zpwrRegenAll, zpwrRegenMost, zpwrRegenCtags, zpwrRegenGtagsCtags, zpwrRegenHistory, zpwrRegenZshCompCache, zpwrRecompile, zpwrRecompileFpath, zpwrRefreshZwc, zpwrCleanCache, zpwrCleanCompCache.
tmux
zpwrAttachSetup, zpwrDetachall, zpwrTmuxSave, zpwrTmuxLoad, zpwrTmux_capture_paner, zpwrTmux_pane_words.
Banners / Display
zpwrAbout, zpwrBannerCounts, zpwrBannerLolcat, zpwrPonyBanner, zpwrNoPonyBanner, zpwrColorTest, zpwr256ColorTest, zpwrAnimate, zpwrMatrix, zpwrFigletfonts, zpwrFortune.
ZLE Widgets
zpwrAcceptLine, zpwrMagicEnter, zpwrSelfInsert, zpwrInterceptSurround, zpwrInterceptDelete, zpwrDeleteLastWord, zpwrLastWordDouble, zpwrClearLine, zpwrExpandAliases, zpwrExpandOrCompleteWithDots, zpwrPasteToBuffer, zpwrEOLorNextTabStop.
Hooks
zpwrPrecmd, zpwrPreexec, zpwrChpwd, zpwrBindPrecmd, zpwrBindPreexecChpwd, zpwrPoll, zpwrTimer.
Plugin Management
zpwrZinitUpdates, zpwrZshPluginCount, zpwrZshPluginList, zpwrVimPluginCount, zpwrVimPluginList, zpwrEmacsPluginCount, zpwrEmacsPluginList, zpwrUpdateDeps, zpwrCleanUpdateDeps.
Network / Remote
zpwrSshRegain, zpwrKillRemote, zpwrMycurl, zpwrTorip, zpwrToriprenew, zpwrGoogle, zpwrOpen, zpwrOpenmygh, zpwrUpload.
Tags / Gtags
zpwrVimZpwrCtags, zpwrVimZpwrGtags, zpwrEmacsZpwrCtags, zpwrEmacsZpwrGtags, zpwrGtagsIntoFzf, zpwrGetGtags, zpwrRegenGtagsCtags, zpwrRegenGtagsPygments, zpwrRegenGtagsType.
$VERB DISPATCH
Every zpwr <arg> invocation routes through autoload/common/zpwr → env/zpwr.zsh (the $ZPWR_VERBS_FILE pointed at by env/.zpwr_re_env.sh), which builds a 462-entry typeset -Ag ZPWR_VERBS associative array at shell start. Each entry is keyed by verb spelling and valued functionName=description. Counts: 462 keys, 460 unique spellings, 372 distinct backing functions — aliases (about/banner both map to zpwrAbout, doctor/doc/checkup all map to zpwrDoctor) account for the gap. zpwr verbs (a.k.a. zpwrNumVerbs, which echoes $#ZPWR_VERBS) reports the 462 key count; the README publishes 460, the count of unique spellings.
Dispatch is a single source $ZPWR_VERBS_FILE "$@" per call — cheaper than re-resolving function names through fpath. Empty argv is shorthand for zpwrCd "$ZPWR". The completion file autoload/comps/_zpwr partitions verbs into regen, clean, and travis groups for grouped Tab descriptions.
// REPRESENTATIVE VERBS
| Verb | Function | What it does |
|---|---|---|
| zpwr about | zpwrAbout | ZPWR ASCII banner. Aliases: banner. |
| zpwr bench | zpwrBench | Benchmark startup time with percentiles and baseline diff. Aliases: benchmark. |
| zpwr doctor | zpwrDoctor | Environment health check. Aliases: doc, checkup. |
| zpwr top | zpwrTop | Live dashboard (panel-of-panels view across env/git/tmux/proc). |
| zpwr flame | zpwrFlame | Flame-graph of shell startup spent in autoload resolution. |
| zpwr startup | zpwrStartup | Startup profile: time per source/autoload. |
| zpwr lint | zpwrLint | Shellcheck/zsh-syntax pass across the tree. |
| zpwr ports | zpwrPorts | Listening ports (lsof/ss) with PID and command. |
| zpwr stale | zpwrStale | Find files untouched past a threshold. |
| zpwr pathaudit | zpwrPathaudit | Audit $PATH entries: dupes, missing dirs, dead symlinks. |
| zpwr gitwho | zpwrGitwho | git who: per-author churn for the current repo. |
| zpwr timeline | zpwrTimeline | History timeline (per-day command counts from $HISTFILE). |
| zpwr aliasrank | zpwrAliasRank | Mine history for most-used aliases. |
| zpwr funcrank | zpwrFuncRank | Rank zsh functions by call count. |
| zpwr deps | zpwrDeps | Function dependency graph + call-chain analysis (aliases: callers). |
| zpwr trace | zpwrTrace | Command trace. |
| zpwr replay | zpwrReplay | Replay a previous command sequence. |
| zpwr watch | zpwrWatch | File watcher with custom on-change action. |
| zpwr snapshot | zpwrSnapshot | Snapshot env (vars, fns, aliases, $PATH). Paired with zpwr restore. |
| zpwr resolve | zpwrResolve | Identify what a bareword resolves to: alias, fn, builtin, file. |
| zpwr wizard | zpwrWizard | Interactive 217-page ZPWR encyclopedia / cheatsheet. |
| zpwr matrix | zpwrMatrix | Matrix-style screensaver / TUI battle. |
| zpwr fortune | zpwrFortune | Show a fortune through cowsay/lolcat. |
@PLUGIN STACK (ZINIT)
ZPWR loads its zsh plugins through zinit. Plugins are listed flat in install/.zshplugins (48 entries), wired with zinit ice turbo-mode directives for lazy loading. The plugin set spans completions, fzf integration, syntax highlighting, history substring search, OMZ libraries / plugins, and ZPWR's own forked plugins under the MenkeTechnologies/* namespace.
// PLUGIN GROUPS
MenkeTechnologies forks
The maintainer's own forks shipped at the head of .zshplugins: fasd-simple, forgit, fzf, fzf-tab, fzf-zsh-plugin, gh_reveal, jhipster-oh-my-zsh-plugin, kubectl-aliases, revolver, zconvey.
Prompt
romkatv/powerlevel10k loaded with a custom ice line that runs zpwrBindPowerline, zpwrBindPowerlineTmux, zpwrBindDirs, and zpwrPrecmd as atinit.
fzf integration
fzf-zsh-plugin, fzf-tab, junegunn/fzf as the binary side; autoloaded fzf/ completion shims tie fzf into vim, emacs, zpwr, git, killall, printf.
OMZ
Oh-my-zsh plugins / libs sniped via zinit snippet OMZP::* / OMZL::* with an atload='zpwrOmzOverrides' hook so ZPWR can rebind any keybinding OMZ steals.
Completion
Compiled .zwc bytecode for completion cache; custom _zpwr, _zcommand, _zcommand_mult, _p, _r, _f, _digs, _dfimage, _ssu, _ssd in autoload/comps/.
Toggle
ZPWR_PLUGIN_MANAGER env var picks between zinit (default) and a no-plugin fallback. Tests in tests/ exercise both paths.
!KEYBINDINGS
ZPWR rebinds the shell from the keyboard up. 228 bindkey statements span zsh's six keymaps (viins, vicmd, visual, menuselect, listscroll, viopp); 80 bind-key directives across 24 tmux configs cover pane / window / session management. The README publishes a generated reference (source keybindings_to_readme.zsh >> README.md) so the bindings stay in sync with the live shell.
// TMUX CONF MATRIX
| File | Role |
|---|---|
| init.conf | Root tmux config; source-file's the rest based on version + OS. |
| tmux_lt_21.conf / tmux_ge_21.conf | Pre/post tmux 2.1 syntax (setw renames, status interval, escape-time). |
| tmux_lt_29.conf / tmux_ge_29.conf | Pre/post 2.9 (window styles, pane-base-index, hooks). |
| tmux_lt_31.conf / tmux_ge_31.conf | Pre/post 3.1 (extended-keys, popup support, format ops). |
| tmux-mac.conf / tmux-linux.conf / tmux-wsl.conf | Per-OS clipboard wiring (pbcopy / xclip+xsel / clip.exe). |
| four-panes / eight-panes / sixteen-panes / thirtytwo-panes (.conf) | Pane-layout presets bound to prefix-driven hotkeys. |
| sixteen-panes-repl.conf / thirtytwo-panes-repl.conf | REPL-oriented variants that pre-launch repl pids per pane. |
| control-window.conf / control-window2.conf / alt-control-window.conf | Master-window navigation bindings (Ctrl-A prefix overlay). |
| fourVertical.conf / learn.conf / google.sh / config-files.conf | Specialty layouts: 4 vertical, learning mode, search-pane spawner, dotfile editor. |
+TOOLING INSTALLED
The install/ directory bootstraps the entire surrounding ecosystem ZPWR depends on. casks.sh + formulae.sh alone invoke brew install across 654 distinct formulas/casks (75 casks + 579 formulae); gems.sh, npm_install.sh, neovim_install.sh, iftop_install.sh, go_install.sh add Ruby / Node / Neovim / iftop / Go toolchains. Vim is set up with install/init.vim + plugin manifests; Emacs config + JetBrains plugin bundles ship in zips ready to drop in.
| File | What it provisions |
|---|---|
| install/casks.sh | Mac GUI apps via brew install --cask: Alacritty, iTerm2, Alfred, Anaconda, Sublime, JetBrains IDEs, Docker Desktop, Postman, OBS, Wireshark, … |
| install/formulae.sh | CLI utilities via brew install: ripgrep, fd, bat, eza, fzf, fasd, gh, tmux, nvim, jq, yq, gnu-sed, gnu-tar, coreutils, … |
| install/mincasks.sh | Minimal cask subset for low-storage installs. |
| install/gems.sh | Ruby gems (lolcat, colorls, rspec, …). |
| install/npm_install.sh | Node CLIs (yarn, pnpm, eslint, prettier, tree-sitter-cli, …). |
| install/go_install.sh | Go binaries via go install (currently empty — prior Go tools replaced by Rust ports). |
| install/neovim_install.sh | Neovim core build / install on systems where the package manager has an out-of-date version. |
| install/iftop_install.sh | Build iftop from source on Linux distros that don't ship it. |
| install/.zshplugins | 48 zinit plugin specs. |
| install/init.vim | Neovim/Vim config + plugin manifest. |
| install/stryke.vim | .stk syntax highlighting / filetype detection. |
| install/jetbrains.zip / jetbrains_windows.zip | Pre-bundled JetBrains IDE keymap / plugins for cross-machine consistency. |
| install/jetbrainsplugins.txt | Plugin manifest used by the IDE's plugin manager scripts. |
| install/Material_jm.icls / install/jm.itermcolors | JetBrains color scheme + iTerm2 palette. |
| install/htoprc | htop config. |
| install/idea.vmoptions | JetBrains JVM options. |
| install/alacritty.toml | Alacritty theme + key bindings + font config. |
| install/conf.df / conf.gls / conf.ifconfig / conf.mount / conf.whois | Stylized output configs for df/gls/ifconfig/mount/whois (colorize hook helpers). |
| install/{compose,learn,mem}.service | systemd unit files for docker-compose / learning daemon / memory monitor. |
| install/hooks | git hooks directory shipped into $GIT_TEMPLATE_DIR on install. |
%TEST SUITE
149 zunit test files / 79,650 lines / 14,277 @test cases. The suite probes every autoload function for existence, source-syntax validity, function-body presence, and correct whence/wordtype classification — then asserts on env-var exports, env-var values, alias bindings, plugin registration, and behavior of the most-used verbs. Naming convention: t-<area>-<dim>-<scope>.zsh (e.g. t-autoload-subdir-body-all.zsh — "autoload, subdir, body presence, all functions"). Each t-*-all.zsh iterates every name and emits one zunit case per name, so the file count understates total assertions.
@test cases| Test family | Dimensions covered |
|---|---|
| t-autoload-* | existence, definedness, body presence, source syntax, fpath resolution, function-type via whence / wordtype / which, funccheck structure. Run against autoload/common/ and every subdir (fzf/, comps/, comp_utils/, darwin/, linux/, systemctl/). |
| t-env-* | env var exports, values, comprehensiveness, defined-in-environment checks. Catches drift between env/.zpwr_env.sh and env/.zpwr_re_env.sh. |
| t-functions / t-callable-fns | 1,068 defined functions all callable without error in a clean shell. |
| t-aliases | 204 aliases all parse and resolve to real commands. |
| t-verb-* | 462 verb keys all dispatch through env/zpwr.zsh without "unknown verb" errors. |
| t-keybind-* | 228 bindkey statements all reference real widgets / functions. |
| t-_support/testfile | Shared fixture sourced into per-case files. |
Suite is driven by zunit (zsh-native test runner with mock support, lifecycle hooks, parallel execution). CI hits both Ubuntu and macOS runners.
.DOCS / ENCYCLOPEDIA
The docs/ tree is the user-facing rendering of ZPWR's introspection: 217 wizard pages (page_001.zsh … page_217.zsh) one zsh per topic, rendered into a 532 KB index.html encyclopedia (consumed by zpwr wizard in-shell and by the static HTML build for the web). 39 screenshots show every tmux preset, prompt theme, and verb in action. Per docs/README.md, the typeset LaTeX/PDF encyclopedia and its generation pipeline are a paid product that lives in the private menke-books repo, not here — only the wizard-page sources and the rendered HTML ship in this tree.
| File | Size | Role |
|---|---|---|
| docs/index.html | 532 KB | The Wizard Encyclopedia: every verb, alias, keybinding, env var, plugin, in one searchable HTML document. 76 chapters / 217 sections, rendered from wizard_pages/. |
| docs/report.html | — | This engineering report. Cross-linked to the encyclopedia via the breadcrumb. |
| docs/wizard_pages/page_NNN.zsh | 217 files | One zsh source page per topic. Each is both a viewer (zpwr wizard 42) and a renderer source for index.html. Validated with zsh -n in the test suite; intro pages use ${#ZPWR_VERBS} so verb totals stay aligned at runtime. |
| docs/hud-static.css | — | Neon HUD theme: CRT scanlines, neon borders, Orbitron / Share Tech Mono fonts, cyan/magenta/green accents on a dark base. |
| docs/tutorial.css | — | Layout for the tutorial / report pages (headers, breadcrumbs, toolbar, content rules). |
| docs/hud-theme.js | — | Theme toggle (light/dark), CRT overlay toggle, neon-pulse toggle, bar-fill animation. |
| docs/README.md | — | Docs-tree map; notes that the typeset LaTeX/PDF encyclopedia + pipeline are a paid product in the private menke-books repo, not this tree. |
| docs/screenshots/*.png | 39 images | Macbook / Raspberry Pi / Rock64 captures of the shell, themes, and verb output. |
| man/man1/zpwr.1 | 8 KB | Top-level man page (man zpwr): overview, primary verbs, env vars. |
| man/man1/zpwrall.1 | 53 KB | Comprehensive meta page (man zpwrall): every verb, every option, every env var. |
=ENV / DISPATCH FILES
9 tracked files in env/ tune the shell environment (.zwc bytecode shadows are generated, not committed). The split is deliberate: .zpwr_env.sh sources once at login; .zpwr_re_env.sh sources on every shell so values that depend on per-shell state (TTY, parent PID, etc.) recompute. Aliases live in .shell_aliases_functions.sh so they can be re-sourced after a plugin clobbers them. zpwr.zsh is the verb dispatch table referenced by autoload/common/zpwr.
| File | Lines | Role |
|---|---|---|
| env/zpwr.zsh | 553 | The 462-entry ZPWR_VERBS table + dispatch logic. Sourced on every zpwr <verb> call. |
| env/.zpwr_env.sh | 243 | One-shot env: $ZPWR, $ZPWR_REPO_NAME, $ZPWR_FORKED_DIR, $ZPWR_LOGFILE, $EDITOR resolution, locale. |
| env/.zpwr_re_env.sh | 218 | Re-sourceable env: per-shell paths, history file, completion cache file, verb-file pointer. Uses zpwrEvalIfNeeded to skip already-set values. |
| env/.shell_aliases_functions.sh | 210 | 204 aliases + helper functions (resourceable after plugin overrides). |
| env/.powerlevel9kconfig.sh | 82 | powerlevel10k/9k prompt segment selection + theming overrides. |
| env/*.zwc shadows | — | Bytecode-compiled forms for cold-load speedup. |
?HISTORY
ZPWR began life as a fork of Hashrocket's Dotmatrix in May 2017 and has been continuously developed since — 6,309 commits, 617 tags, 9 years. git shortlog attributes 11,358 of 11,360 commits (across all branches) to MenkeTechnologies; the remaining 2 are from an early collaborator (MichaelDimmitt). The active version line is v48.x (latest tag v48.9.2). Recent commits show ongoing migration to the new stryke shell and perlrs (Rust replacement for perl) across helper scripts.
// RECENT WORK (last 18 commits)
| SHA | Subject |
|---|---|
| 7b5746c | docs: regenerate encyclopedia index.html from current source |
| 0b1daf0 | docs: reconcile stale references and counts with current code |
| 59fe587 | docs: carve Dotmatrix out as narrow dev-scaffolding ancestor |
| ca4e4eb | docs: add Category Of One positioning |
| 0217c2e | Remove regenpdf verb + tests/docs for encyclopedia generation (moved to private menke-books) |
| a7d7226 | gitignore: paid encyclopedia source + generation pipeline now in private menke-books |
| 71569b0 | docs: sync counts with environmentcounts |
| f729ed4 | docs: LOC 186k → 190k |
| 3845e99 | docs(html): sync index.html with README refresh — v48.9.2, 149 tests |
| 80b8700 | tests: zpwrRename: dir-skip invariant, spaced-name quoting, non-match no-op |
| 98f87b9 | docs: refresh stale counts |
| 6f0e993 | rename source |
| 7f816f8 | 0a |
| d1fbb03 | rework fzf environment cache to use byte offsets for speed |
| 32e9e95 | ci: queue runs instead of cancel-in-progress on rapid pushes |
| 75a8d76 | no autoload +X |
| df9cc3c | fix zpwr environment counts |
| 99dcdc6 | no cargo force install powerliners |
;KEY DESIGN DECISIONS
Why ZPWR is shaped the way it is. Each call-out below is a decision the project could have gone the other way on, with the reasoning for the path taken.
Autoload over Source
Every function is a separate file under autoload/common/, picked up by zsh's autoload -Uz mechanism the first time it's called. A fresh shell never reads a function it doesn't use — cold start stays under $ZPWR_BENCH-able levels even with 533 functions on disk.
Verb Table over Subcommand Files
462 verbs route through one associative array in env/zpwr.zsh rather than 462 dispatch files. Alias spellings cost one extra key, not a duplicate file; the completion file walks the same table for Tab descriptions.
One Repo, Many Toolchains
install/ doesn't just install zsh plugins — it owns the brew formulas, npm globals, vim/nvim configs, JetBrains keymap, iTerm colors, and systemd units. A new machine reaches parity with one install/s invocation; nothing assumed about the host.
Cached Everything (local/)
Git-repo dirty state, alias usage rankings, completion bytecode, encyclopedia render, zcompdump, snapshot tarballs — all under local/. The zpwr regen verb family rebuilds caches in dependency order; zpwr clean family blows them away when contamination is suspected.
Re-sourceable Env Split
env/.zpwr_env.sh sources once; env/.zpwr_re_env.sh sources every shell. The split lets long-lived env (paths, repos) cache between shells while per-shell state (TTY, parent PID, host) recomputes — without forcing one or the other onto everything.
Per-tmux-Version Configs
tmux config syntax has shifted enough times (2.1, 2.9, 3.1) that one tmux.conf can't span all of them. ZPWR's init.conf dispatches to tmux_(lt|ge)_(21|29|31).conf on load — one tmux config tree works against every host in the fleet.
Tests as Reflection Probes
The 79k-line zunit suite is mostly "for each name in X, assert Y." Drift in autoload coverage, env-var exports, or alias bindings surfaces as a failing case — before the contributor finds out at runtime that a shell rebind silently dropped a function.
Wizard as Source-of-Truth
217 zsh "wizard pages" double as in-shell viewers (zpwr wizard N) and as the input to docs/index.html. One copy of every fact — the encyclopedia and the in-shell help never drift, because they're regenerated from the same files.
OMZ Snippet, Not Full Theme
OMZ plugins/libraries are sniped via zinit snippet OMZP::* / OMZL::* instead of installing the whole framework. Saves the bulk; atload='zpwrOmzOverrides' hook rebinds any keybinding OMZ trampled.
Stryke is the Bet
The README announces ZPWR will migrate to zshrs (the Rust login shell built on strykelang) "soon". Current commits show perlrs already replacing perl in helper scripts — the migration is already in flight one binary at a time, not a flag-day port.