profile/doc/todo.md

profile — to-do list

Items marked [easy], [medium], or [hard] give a rough effort hint. Items marked [breaking] would change existing behaviour and require a version-bump.

---

Shell / compatibility

• ZSH compatibility layer — most functions work already; the remaining blockers are local -A (no associative arrays in ZSH without typeset -A) and local -n namerefs. A thin compatibility shim would open the project to ZSH users. [hard]
• Bash completion — add a more bash completion directory and write _profile_upgrade, _taz, _utaz, _meteo, etc. completions so that <Tab> works on all public functions. [medium]

---

Prompt & theming

• Git branch in prompt — show the current branch name (with dirty and upstream drift indicators) in the PS1 bar when inside a Git repository, gated by [prompt] config keys. [medium]
• Virtual-env / conda indicator — detect $VIRTUAL_ENV / $CONDA_DEFAULT_ENV and display the active environment in the prompt bar. [easy]
• Session context markers — display lightweight session markers (ssh, tmux, screen) at the end of the prompt bar, gated by [prompt] config keys. [easy]
• True-colour terminal auto-detection — query $COLORTERM and $TERM at load time; automatically fall back from a 24-bit theme to its 16-colour equivalent when the terminal does not support true colour. [medium]
• True-colour variants of other themes — create monokai-tc.theme, abyss-tc.theme, etc. using the same \e[38;2;R;G;Bm approach as the Solarized themes. [easy] (per theme)
• Theme preview command — add a theme_preview (or profile_theme) function that renders a colour swatch and a sample prompt line for the currently loaded theme, so users can evaluate themes without reloading the session. [medium]
• load_theme — DEFAULTCOL rebuild — after overriding DEFAULTFG and DEFAULTBG, automatically recompute DEFAULTCOL from the new values instead of requiring the theme file to set it explicitly. [easy]

---

Module improvements

compress

• taz progress bar — show a pv / dd-based progress indicator when compressing large trees, gated behind a -p flag. [medium]
• utaz integrity check — run tar -tOf / unzip -t / 7z t before extracting and abort if the archive is corrupt. [easy]

filefct

• findbig / findzero / finddead — fd integration — optionally use fd instead of find when available for faster traversal. [easy]
• file_stats — human-readable totals — add --human flag to emit sizes in K/M/G instead of bytes. [easy]

info

• showinfo fallback — when neither neofetch nor fastfetch is installed, print a minimal sysinfo block (hostname, OS, kernel, uptime, CPU, RAM) using pure Bash + /proc. [medium]

net

• dwl resume support — pass -C - to curl / --continue-at - to wget for interrupted downloads; gate behind a -r flag. [easy]
• myextip multiple providers — fall back to a secondary URL (configurable via MYEXTIP_FALLBACK_URL) when the primary times out. [easy]

processes

• ku dry-run flag — add -n / --dry-run to print what would be killed without acting. [easy]

pwd

• genpwd passphrase mode — add -w / --words N to generate word-based passphrases (diceware-style) from /usr/share/dict/words. [medium]

ssh

• SSH agent management — add ssh_agent_start / ssh_agent_stop helpers that start a persistent ssh-agent, add configured keys, and survive re-login via a socket stored in ~/.ssh/agent.env. [medium]
• rmhost glob support — allow rmhost '*.example.com' to remove all matching entries in one call. [easy]

updates

• Automatic update check age — store a timestamp in ~/.cache/profile_last_check; skip the network request in check_updates -q if the last check was less than UPDT_CHECK_INTERVAL hours ago (configurable, default 24). [medium]
• Changelog display — after a successful profile_upgrade, fetch and display CHANGELOG.md entries newer than the previously installed version. [medium]

---

Structure

• Helpers must not stay in the environment (do first) — internal functions (_ prefix, helpers/) are not part of the user interface, yet 16 of them are export -f, so they leak into the environment of every child process. By design they should only exist where they are needed:
  • stop exporting helpers by default; unset the ones only needed at load time (as profile.sh already does for parse_conf, load_alias, ...);
  • a helper stays exported only when an exported public function calls it and must work in a child bash (bash -c, find -exec, xargs), which has to be checked and documented one by one (otherwise that public function is no longer exported either, or waits for the stub mechanism below);
  • add a check (shellcheck-like script or bats test) listing exported functions starting with _, so none comes back unnoticed. This is the first step: it does not depend on the lazy loading below, which builds on it. [medium]
• Load code on demand (stubs, lazy loading, optional unloading) — today every module is sourced at startup (about 63 ms, 109 functions) and 80 functions are exported (about 250 KB of environment inherited by every external command, which makes each one about 25 % slower and eats ARG_MAX). Replace this by:
  • Stubs: each lazy command is a tiny generated function (rain() { _lazy rain "$@"; }), the only thing exported. The stubs come from a command-to-module index, built at upgrade time from a # provides: ... header in each module (so help, type and completion still see every command).
  • Lazy loading (_try_load): the first call sources the module and its helpers/<module>.sh (and the modules it depends on, declared in the header), then runs the real function (_exec). The code stays loaded afterwards. Helpers and implementations are no longer exported, which also removes them from the environment of child shells.
  • Optional unloading (_free, e.g. PROFILE_UNLOAD=1): after the call, put the stub back instead of unsetting the function. Must be idempotent (Ctrl-C or return skip the cleanup), must not free code still referenced by a trap (_rain_stop, WINCH handler) or used by a running caller (reference count), and costs about 4 ms per call, so it is not the default.
  • Always resident: disp, conf, debug, prompt (and the DEBUG timer hook), lang shortcuts and help. With unloading, state kept across calls (pwd pool, current theme, settrace) must live in variables that are not freed. Lazy candidates: compress, filefct, fun, git, info, net, packages, processes, pwd, rain, ssh, updates.
  • To solve: load_conf/CONF_* must stay available at call time; child shells need MYPATH and the loader exported to resolve stubs; tracebacks show the loader frames. Do it after the test suite exists, as regressions would be silent. [hard]

---

Infrastructure

• Test suite — add a test/ directory with bats (Bash Automated Testing System) unit tests for pure functions (expandlist, genpwd, pwdscore, isipv4, isipv6, parse_conf, load_theme, …). Target for CI. [hard]
• CI pipeline — Gitea Actions (or similar) job that runs shellcheck and the bats suite on every push. [medium]
• profile_status function — print a diagnostic summary: installed version, active theme, loaded modules, detected Bash version, interactive / login shell flags, and profile.conf path. [easy]
• profile_uninstall function — remove the source line from ~/.bashrc / ~/.profile and optionally delete the install directory, with a dry-run mode. [medium]
• disp syslog integration — add a DISP_SYSLOG=<context> config key that additionally pipes E/W messages to logger. [easy]
• XDG base-dir support — honour $XDG_CONFIG_HOME as an alternative location for profile.conf so users can keep ~ tidy. [medium] [breaking]