# Toolkit

This is what my `~/scripts` folder turned into once I stopped treating shell scripts as
disposable.

One `tool` command in front of everything. Type `tool` for a TUI, or `tool health-check`
to run one directly. The launcher auto-discovers scripts from the category directories,
so adding a script is dropping a file in the right folder — there is no registry to
update and no case statement to extend.

```
toolkit/                 # ~/scripts on my machine
├── tool                 # launcher — auto-discovers everything below
├── config/toolkit.conf  # key-value config: SCRIPTS_DIR, PROJECTS_DIR, NOTES_DIR
├── lib/                 # colors, ui, config, utils — sourced by every script
├── system/              # health-check, sysmon, port-manager, docker-cleanup, cleanup,
│                        #   disk-analyzer, ollama-manager, proc-top, service-status, update-all
├── dev/                 # git-helper, venv-manager, project-init
├── general/             # notes, extract, cheat, weather, bookmark, ff
└── net/                 # ip-lookup, ssl-check, holehe-check, passmorph, qr
```

Twenty-four scripts across the four category directories, four files in `lib/`, and the
launcher.

## The shared library is the point

Four files in `lib/` do most of the work of making this feel like one program instead of
two dozen:

- **`colors.sh`** — the palette. Nothing hardcodes an escape sequence.
- **`ui.sh`** — Nerd Font icon constants, `print_success` / `error` / `warning` / `info` /
  `loading`, box drawing, headers, separators.
- **`config.sh`** — loads `toolkit.conf` and exports `SCRIPTS_DIR`.
- **`utils.sh`** — `command_exists`, `require_command`, `validate_name`, `confirm_action`.

Almost every script sources these, so a success message looks the same everywhere, a destructive
action always confirms the same way, and a missing dependency always produces the same
error rather than a raw `command not found`.

That consistency is worth more than any individual script. The reason a folder of shell
scripts usually rots is that each one is written in a slightly different dialect by a
slightly different version of you, and after a year none of them behave alike. A shared
UI layer makes the dialect a property of the toolkit instead of the afternoon.

There's also an authoring guide in the repo — the conventions, patterns and design rules
in one document — which I hand to an AI assistant when I want a new script that fits.
Writing the conventions down once turned out to be the thing that kept them.

## Portability

Written in Bash, run under Zsh, and portable across distros and WSL2. WSL2 is the awkward
case and it's the one I actually use, so a couple of scripts exist purely to paper over
the seam between the two filesystems — converting a Windows path into a WSL one, for
instance, which is a thing I did by hand often enough to be annoyed by.

A handful of the scripts are Python where shell was the wrong tool. The launcher doesn't
care which language a script is written in; it cares that it's executable and lives in a
category directory.

## Stack

Bash, some Python, Nerd Font glyphs for the UI, no dependencies beyond coreutils and
whatever an individual script declares through `require_command`.
