🧱 ZSHAND Shared Functions Reference¶

📋 Low-level primitives used by startup scripts, core modules, and user scripts (init.d/, post.d/, rc.d/). These are loaded early and persist for the entire session (unlike _az_* startup functions which are unset after init).

📂 Function Reference¶

🫧 Unified IO Library (`00_gum_io.zsh`)¶

The primary IO library for all framework output. Uses charmbracelet/gum when installed for beautiful TUI output, with graceful fallback to print -P / ANSI codes.

#	File	Scope
00	`00_gum_io.zsh`	All IO primitives: core log, rich, interactive, timer

Gum detection is cached at source time in _ZSHAND_HAS_GUM (integer flag). See docs/external/gum.md for full reference.

💬 Core Log Functions¶

Defined in 00_gum_io.zsh. The old files (01–05) are backward-compat stubs that delegate to this library.

Function	Channel	Purpose
`stderr_error`	stderr	Red `ERROR:` message to stderr
`stderr_warn`	stderr	Yellow warning to stderr
`echo_info`	stdout	Blue info message to stdout
`echo_ok`	stdout	Green success message to stdout

stderr_error "Config file not found: $file"
stderr_warn "Falling back to defaults"
echo_info "Processing 42 files..."
echo_ok "All files compiled"

🎨 Rich Output Functions¶

Function	Purpose
`az_banner "text"`	Double-border title banner
`az_header "text"`	Bold section header
`az_note "text" [color]`	Styled callout box
`az_divider`	Horizontal divider line
`az_step N M "label"`	Step counter `[N/M] label`
`az_done "text"`	Green completion banner
`az_progress "✓" "green" "msg"`	Progress step indicator
`az_styled_box "color" ["text"]`	Colored border box

🖱️ Interactive Functions¶

Function	Purpose
`az_spin "title" cmd...`	Spinner with ✓/✗ result
`az_confirm "prompt"`	Y/N confirmation
`az_choose "A" "B"`	Single selection menu
`az_filter_multi` (piped)	Multi-select with fuzzy search
`az_input "prompt" "default"`	Text input prompt

⏱️ Timer Functions¶

Function	Purpose
`az_timer_start`	Record start time
`az_elapsed`	Print elapsed duration

🔀 Backward-Compat Stubs¶

The original files still exist as thin stubs that delegate to 00_gum_io.zsh:

#	File	Stub for
01	`01_stderr_error.zsh`	`stderr_error`
02	`02_stderr_warn.zsh`	`stderr_warn`
04	`04_echo_info.zsh`	`echo_info`
05	`05_echo_ok.zsh`	`echo_ok`

📊 Logging & Timing¶

#	File	Function	Purpose
03	`03_init_log_append.zsh`	`init_log_append`	Timestamped entry to `init.log`
06	`06_time_millis.zsh`	`time_millis`	High-resolution timestamp (ms)
15	`15_load_file_timed.zsh`	`load_file_timed`	Source `.zsh` file with timing
16	`16_zrun.zsh`	`_zrun`	Logged command runner (telemetry)

init_log_append "My script: starting"

local t0=$(time_millis)
# ... work ...
echo "Took $(($(time_millis) - t0))ms"

load_file_timed "$ZSHAND/core/06_engine.zsh"

✅ Assertions¶

#	File	Function	Purpose
07	`07_cache_dir.zsh`	`cache_dir`	Print `$ZSHAND_CACHE` path
08	`08_assert_dir_exists.zsh`	`assert_dir_exists`	Require directory exists
09	`09_assert_file_exists.zsh`	`assert_file_exists`	Require file exists
10	`10_assert_function_exists.zsh`	`assert_function_exists`	Require function is defined

assert_dir_exists "$ZSHAND/core" "Core directory" || return 1
assert_file_exists "$config" "Config file" || return 1
assert_function_exists "zprime" || return 1

🔧 Source Helpers¶

#	File	Function	Purpose
11	`11_source_with_zwc.zsh`	`source_with_zwc`	Source `.zsh` preferring `.zwc` bytecode

source_with_zwc "$ZSHAND_CONFIG_DIR/foo.zsh"  # uses foo.zsh.zwc if newer

🐛 Debug Helpers¶

#	File	Function	Purpose
12	`12_debug_echo_cmd.zsh`	`debug_echo_cmd`	Debug: print `CMD: ...`
13	`13_debug_echo_result.zsh`	`debug_echo_result`	Debug: print `✓/✗/→ ...`
14	`14_debug_eval_test.zsh`	`debug_eval_test`	Debug: eval and report

Active only when ZSHAND_DEBUG=1.

📋 Clipboard¶

#	File	Function	Purpose
17	`17_clipboard_copy.zsh`	`clipboard_copy`	Cross-platform clipboard copy
18	`18_clipboard_paste.zsh`	`clipboard_paste`	Cross-platform clipboard paste

echo "text" | clipboard_copy
clipboard_paste
clipboard_copy --no-backup --timeout 5 "content"
clipboard_paste --cache --fallback "default"

Platform support: Wayland (wl-copy/wl-paste), X11 (xclip/xsel), macOS (pbcopy/pbpaste), WSL (clip.exe/PowerShell).

Features: Auto-backup, retry with backoff, content verification, CRLF→LF normalization, secure permissions (chmod 600).

🔄 Load Behavior¶

Loaded together with startup/ in one alphabetical pass by zshrc.zsh
Persist for the entire shell session (never unset)
Compiled into the shared_functions bundle by zprime
Available in init.d/, post.d/, rc.d/, and all user scripts

Document	Purpose
🫧 external/gum.md	Gum TUI enhancement docs
📂 shared_functions/README.md	In-tree quick reference
🚀 STARTUP.md	Startup scripts (loaded alongside)
🏗️ ARCHITECTURE.md	Load order in boot sequence
📋 shared_functions/clipboard.md	Detailed clipboard docs