# ops-toolkit

Team-blessed tools, configs, and helpers for ops techs. Clone it, run the
bootstrap, and you are on the same tool set the rest of the team trains on --
no independent research required.

Target environment: Ubuntu 22.04/24.04, bash, apt-first. Version FLOORS are
enforced where a tool needs one; nothing is version-pinned unless a pack's
README says otherwise and why.

## Quickstart

    git clone https://git.baldurkeep.com/git/ops/ops-toolkit.git ~/ops-toolkit
    cd ~/ops-toolkit
    bash bootstrap.sh --list             # see what is available
    bash bootstrap.sh --dry-run --all    # see exactly what would change
    bash bootstrap.sh --all              # install everything

Always run the dry-run first. Every mutation the installers would make is
printed there; nothing in this repo changes your machine silently.

Note: invoke scripts as `bash script.sh` (do not rely on the executable bit;
commits from Windows clients strip it, which is cosmetic under this rule).

## Packs

| Pack       | What it gives you                                            |
|------------|--------------------------------------------------------------|
| tmux       | Durable terminal sessions; team baseline config + plugins    |
| shell      | Team aliases and helpers, sourced via one .bashrc fence      |
| ops-scripts| Shared scripts in ~/.local/bin (validate-paste, ...)         |
| tmuxinator | One-command tmux project workspaces from YAML                |

Each pack has its own README (why the team uses it, what installs, house
rules) and numbered component installers you can run standalone:

    bash packs/tmux/install-020-config.sh    # just relink the tmux config

## How installs behave (the contract)

- **Symlink for team configs** (`~/.tmux.conf`, `~/.local/bin/*`): a
  `git pull` here updates everyone. Anything replaced is backed up first to
  `<file>.bak.<timestamp>`.
- **Copy-if-absent for user-edited files** (tmuxinator project YAMLs):
  re-installs never clobber your edits.
- **One fenced block in `~/.bashrc`**: re-installs replace the fence in
  place, never append duplicates. Your content outside the fence is never
  touched.
- **Personal overrides are first-class**: `~/.tmux.conf.local` and your own
  dotfiles outside the fence. The toolkit never ships or edits them.
- **Idempotent and loud**: re-running any installer on a converged machine
  prints OK/no-op lines and changes nothing. `TOOLKIT_DRY_RUN=1` (or
  `bootstrap.sh --dry-run`) previews every mutation.
- Exit codes everywhere: `0` proceed, `1` a step failed, `2` precondition
  missing (tool absent, version below floor, bad usage).

## Repo rules

- ASCII-only, LF endings (`.gitattributes` enforces normalization; check
  with `grep -rnP '[^\x00-\x7F]' --include='*.sh' .`).
- No environment-specific values in shipped files: no IPs, IDs, hostnames,
  or credentials. Templates carry placeholders; scripts discover at runtime.
- Every script opens with a header: purpose, what it MUTATES, usage, exit
  codes. `Mutates NOTHING` scripts are safe to run out of curiosity.
- New packs: copy an existing pack's shape (`install-pack.sh` orchestrator +
  numbered `install-NNN-*.sh` components, numbered with gaps so steps can be
  inserted later) and source `lib/lib-install.sh` for the shared hardening.
- Changes go through PR. Tool adoption debates belong in the pack README so
  the rationale travels with the tool.