wuast-shell

wuast-shell is the source-of-truth shell setup for this repository's Debian 13 and macOS machines. It installs one selected tool set everywhere, applies repo-managed home files through chezmoi, and keeps package manifests, doctor checks, and documentation aligned.

Usage

• just setup installs packages, applies the managed shell state, changes the login shell when safe, generates completions, runs assisted account or secret setup when required, and runs doctor.
• just apply forcefully applies repo-managed home state. It is backup-free and only intended for paths owned by this repository.
• just upgrade performs the selected package, plugin, completion, apply, and doctor refresh path.
• just doctor checks required commands and setup state.
• Quality commands are just format, just lint, just test, just e2e, and just everything.

Agent Notes

• Package manifests under packages/ are the source of truth. Do not hardcode selected tools elsewhere when a manifest can be read.
• Standard command names keep their native CLI contracts. Use modern tools explicitly, or use the distinct interactive shortcuts in aliases.zsh.
• Generated XDG state, cache, share files, completions, logs, stamps, and secrets are machine-local. Do not edit or commit them from the repository.
• Daily startup upgrades are mandatory by design and must continue into a usable shell with a loud warning if an upgrade step fails.

Generated Tool List

Tool	Category	Commands	Packages	Description
zstd	archive	zstd	brew: zstd	Extracts modern compressed release archives used by setup-managed tools.
ouch	archives	ouch	brew: ouch	Handles common archive formats through one friendly interface.
pay-respects	command correction	pay-respects	github: iffse/pay-respects	Suggests fixes for failed shell commands from the latest verified upstream release.
Docker CLI	containers	docker	brew: docker	Installs the Docker CLI without installing or managing a Docker runtime.
lazydocker	containers	lazydocker	brew: lazydocker	Provides a Docker TUI when a runtime is already available.
chafa	developer helpers	chafa	brew: chafa	Renders image previews in capable terminals.
direnv	developer helpers	direnv	brew: direnv	Loads trusted project environments after explicit direnv allow.
hyperfine	developer helpers	hyperfine	brew: hyperfine	Benchmarks shell startup and command performance when needed.
mise	developer helpers	mise	brew: mise	Manages project runtimes without installing global language toolchains.
sd	developer helpers	sd	brew: sd	Provides safer common text replacements without shadowing sed.
tokei	developer helpers	tokei	brew: tokei	Counts code, comments, and blanks across repositories.
uv	developer helpers	uv	brew: uv	Manages Python tools and virtual environments without global pip installs.
glow	docs	glow	brew: glow	Displays Markdown documentation cleanly in the terminal.
tealdeer	docs	tldr	brew: tealdeer	Provides practical command examples from tldr pages.
GNU nano	editor	nano	brew: nano	Acts as the default terminal editor with visible exit and save shortcuts.
FiraCode Nerd Font	font	n/a	cask: font-fira-code-nerd-font; github: ryanoasis/nerd-fonts	Provides the expected glyphs and ligatures for the prompt and terminal UI from Homebrew cask or latest Nerd Fonts release.
Ansible	infrastructure	ansible	brew: ansible	Keeps Ansible available for infrastructure workflows outside this shell setup.
ansible-lint	infrastructure	ansible-lint	brew: ansible-lint	Checks Ansible content used by related infrastructure work.
Helm	kubernetes	helm	brew: helm	Manages Kubernetes charts when a cluster workflow needs them.
k9s	kubernetes	k9s	brew: k9s	Provides an interactive Kubernetes dashboard in the terminal.
kubectl	kubernetes	kubectl	brew: kubectl	Provides Kubernetes command-line access without requiring a live cluster during startup.
Stern	kubernetes	stern	brew: stern	Streams Kubernetes logs across matching pods.
Atuin	modern cli	atuin	brew: atuin	Provides searchable shell history without requiring sync by default.
bat	modern cli	bat	brew: bat	Displays files with syntax highlighting and Dracula-friendly colors.
bat-extras	modern cli	batgrep, batdiff, batman, batpipe, prettybat	brew: bat-extras	Adds explicit bat-based helpers for grep, diffs, man pages, pipes, and pretty output.
btop	modern cli	btop	brew: btop	Replaces top for daily interactive resource monitoring.
delta	modern cli	delta	brew: git-delta	Improves Git diffs, blame, and pager output.
duf	modern cli	duf	brew: duf	Shows mounted filesystems in a compact, readable table.
dust	modern cli	dust	brew: dust	Summarizes disk usage with clearer visual output than du.
eza	modern cli	eza	brew: eza	Replaces daily directory listings with colorful, git-aware output.
fd	modern cli	fd	brew: fd	Provides a friendly, fast replacement for daily file discovery.
gdu	modern cli	gdu	brew: gdu	Provides an interactive disk-usage workflow when a full analyzer is useful.
lazygit	modern cli	lazygit	brew: lazygit	Provides a Git TUI while scripts and agents keep normal git semantics.
lsof	modern cli	lsof	brew: lsof	Supports local port and open-file inspection helpers.
procs	modern cli	procs	brew: procs	Shows process lists in a clearer, colored table.
ripgrep	modern cli	rg	brew: ripgrep	Provides the default fast recursive text search.
ripgrep-all	modern cli	rga	brew: ripgrep-all	Extends ripgrep-style search across richer document formats.
ssh-copy-id	modern cli	ssh-copy-id	brew: ssh-copy-id	Keeps the safe SSH key-copy helper available without changing SSH host policy.
tea	modern cli	tea	brew: tea	Adds Forgejo/Gitea metadata workflows alongside plain Git over SSH.
xh	modern cli	xh	brew: xh	Provides a concise HTTP client for APIs and downloads.
zoxide	modern cli	zoxide	brew: zoxide	Learns frequently used directories and makes navigation faster.
doggo	network	doggo	brew: doggo	Improves daily DNS lookups.
gping	network	gping	brew: gping	Shows ping latency trends directly in the terminal.
trippy	network	trip	brew: trippy	Diagnoses network paths with a modern terminal UI.
Bats	quality	bats	brew: bats-core	Runs the repository's shell behavior tests.
ShellCheck	quality	shellcheck	brew: shellcheck	Finds shell script defects during local verification.
shfmt	quality	shfmt	brew: shfmt	Formats shell scripts consistently.
GnuPG	security	gpg	brew: gnupg	Supports optional signed Git commits.
Antidote	shell core	antidote	brew: antidote	Loads the curated zsh plugin bundle without startup-time downloads.
chezmoi	shell core	chezmoi	brew: chezmoi	Deploys the managed home files from this repository without replacing unrelated user state.
fzf	shell core	fzf	brew: fzf	Powers fuzzy file, directory, and completion workflows.
Git	shell core	git	brew: git	Provides normal Git over SSH and repo self-update support.
Homebrew	shell core	brew		Installs and updates the selected cross-platform tool set.
Homebrew zsh	shell core	zsh	brew: zsh	Modern zsh is the interactive shell baseline for the whole setup.
just	shell core	just	brew: just	Provides the repository command surface, including setup and verification recipes.
Python	shell core	python3	brew: python	Runs repository tooling such as manifest validation and README generation.
Starship	shell core	starship	brew: starship	Renders the Dracula-themed prompt.
zsh-patina	shell core	zsh-patina	brew: michel-kraemer/zsh-patina/zsh-patina; github: michel-kraemer/zsh-patina	Highlights commands and paths in the interactive shell.
jq	structured data	jq	brew: jq	Processes JSON data from APIs, logs, and command output.
Mike Farah yq	structured data	yq	brew: yq	Provides the Go-based yq v4 behavior consistently on macOS and Debian.
Miller	structured data	mlr	brew: miller	Handles tabular and record-oriented text data.
VisiData	structured data	vd	brew: visidata	Opens structured data in an interactive terminal spreadsheet.