docs: add Debian 13 (trixie) migration plan

docs/debian-13-migration-plan.md

@@ -0,0 +1,137 @@
+# Debian 13 ("trixie") Migration Plan
+
+Goal: make this dotfiles repo fully suited for **Debian 13 (trixie)** so a fresh Debian install can be brought up to the same state as the current Fedora setup.
+
+Working branch: `debian-13` (base: `master`).
+
+---
+
+## 1. Summary of what changes
+
+The repo is mostly distro-agnostic already (shell rc files, aliases, nvim via NvChad + Mason, Flatpak list, GitHub-downloaded dev tools). The Fedora coupling is concentrated in:
+
+1. **Package manager + detection** (`main-setup.sh`, scripts 00/01) — mostly *works* for Debian already since detection returns `debian` → `apt`, but package *names* and repos differ.
+2. **Fedora-only .NET script** (`03-fedora-dotnet-setup.sh`) — needs a distro-agnostic (or Debian-specific) counterpart.
+3. **README + comments** referencing Fedora-only steps/groups.
+4. Several **Debian 13 gotchas** (PEP 668 pip, `dnsutils` → `bind9-dnsutils`, `bat` → `batcat`, missing upstream-only tools like `kubectl`/`gh`/`terraform`/`minikube`/`k9s`, `sudo` not always present, Microsoft repo for trixie).
+
+---
+
+## 2. Debian 13 facts that drive the changes
+
+| Topic | Fedora behavior | Debian 13 (trixie) behavior |
+|---|---|---|
+| Package manager | `dnf` / `rpm -q` | `apt` / `dpkg-query` (already handled) |
+| `sudo` | preinstalled | **not always installed** on fresh installs |
+| pip | system pip installs OK | **PEP 668** blocks `pip install --user` (`externally-managed-environment`) |
+| `dnsutils` | `bind-utils` | package renamed to `bind9-dnsutils` (trixie) |
+| `bat` | binary `bat` | package ships **`batcat`**, needs `bat` symlink/alias |
+| `fd-find` | binary `fd` | binary **`fdfind`**, script already symlinks |
+| `.NET` | MS repo for Fedora + `moby-engine` | MS repo for `debian/13` (`packages-microsoft-prod.deb`) or `dotnet-install.sh` |
+| Docker | `moby-engine` | `docker.io` (Debian) or `docker-ce` (Docker repo) |
+| PostgreSQL | needs `postgresql-setup --initdb` | cluster auto-created by package scripts |
+| `kubectl`/`gh`/`terraform`/`minikube`/`k9s` | in COPR/DNF repos | **not in Debian main** → add upstream apt repos or download `.deb` |
+| `chsh` | `util-linux-user` package | in base util-linux; needs password/sudo to change shell |
+| libvirt group | `libvirt` | same `libvirt` group (add user) |
+| default shell | zsh setup via OhMyZsh scripts | zsh not default; needs `chsh` after install |
+
+---
+
+## 3. File-by-file plan
+
+### `main-setup.sh`
+- [ ] Keep existing `detect_linux_distro()` — already returns `debian` for trixie (`ID=debian`). Verify `sudo` present; if missing, warn to `su -`/install `sudo` first (or auto-detect root).
+- [ ] Replace the Fedora-only prompt for `03-fedora-dotnet-setup.sh` with a distro-agnostic `.NET` prompt (new `03-dotnet-setup.sh`), OR gate on both `fedora` and `debian`.
+- [ ] Consider exporting `DEBIAN_CODENAME`/`DISTRO_VERSION` (from `/etc/os-release`) for downstream repo URLs.
+
+### `scripts/00-system-prep.sh`
+- [ ] `apt update && apt upgrade` path already correct. Add optional: install `sudo`, `curl`, `gnupg`, `ca-certificates`, `software-properties-common`/`apt-transport-https` prerequisites early.
+- [ ] (Optional) enable `contrib`/`non-free-firmware` components in `/etc/apt/sources.list.d/debian.sources` — needed for some firmware/tools.
+
+### `scripts/01-package-install.sh`
+- [ ] Split `BASE_PACKAGE_LIST` into truly-common + distro lists; on Debian drop anything not in trixie and add Debian equivalents.
+- [ ] **Rename fixes (Debian branch of `DISTRO_SPECIFIC_PACKAGES`):**
+  - `dnsutils` → `bind9-dnsutils`
+  - add `bat` handling: after install, `ln -sf /usr/bin/batcat /usr/local/bin/bat`
+  - add `sudo`, `ca-certificates`, `gnupg`, `curl` (ensure present)
+  - add `libvirt-daemon-system`, `virtinst`, `qemu-kvm`, `bridge-utils` for virt-manager
+  - add `zsh` post: `chsh -s /usr/bin/zsh` (or instruct)
+  - `python3-pip` stays, but flag PEP 668 handling (see 02)
+  - `docker.io` + `docker-compose` **or** wire Docker CE repo (defer to decision in §4)
+- [ ] **Upstream repo tools not in Debian main** — install in this script or a new `05-` script:
+  - `gh` → GitHub CLI apt repo (`https://cli.github.com/packages`)
+  - `terraform` → HashiCorp apt repo
+  - `kubectl` → Kubernetes apt repo (`pkgs.k8s.io`)
+  - `k9s`, `minikube` → GitHub `.deb` releases (minikube official `.deb` exists)
+- [ ] Flatpak list unchanged (distro-agnostic). Note VS Code Flatpak vs MS repo decision in §4.
+
+### `scripts/02-dev-tools-setup.sh`
+- [ ] **pynvim PEP 668 fix:** replace `pip install --user pynvim` with `python3 -m pip install --user --break-system-packages pynvim`, or (cleaner) install into NvChad's venv, or note `pipx`. 
+- [ ] Rest is GitHub-download based → distro-agnostic; verify `unzip`, `tar`, `wget` present.
+- [ ] `dive` already handles `.deb` via `dpkg -i` on apt — good.
+- [ ] Go/Rust/Nerd Font/Oh-My-Posh/Helm/kubectx/stern/trivy/AWS — no changes needed.
+
+### `scripts/03-fedora-dotnet-setup.sh` → split/generalize
+- [ ] Rename to **`03-dotnet-setup.sh`** and branch by `$PACKAGE_MANAGER`:
+  - **Fedora:** keep existing RPM/MS-repo path.
+  - **Debian:** add MS Debian repo `https://packages.microsoft.com/config/debian/13/packages-microsoft-prod.deb` (verify trixie support; fall back to `dotnet-install.sh` if repo is unavailable for trixie) then `apt install dotnet-sdk-10.0` (or 8/9 fallback loop like Fedora).
+  - Alternatively use official **`dotnet-install.sh`** for both — fully distro-agnostic, no repo dependency.
+- [ ] Replace Fedora-specific db/container section with Debian equivalents:
+  - PostgreSQL: `apt install postgresql` (cluster auto-init — remove `postgresql-setup --initdb` step for Debian; just `systemctl enable --now postgresql`).
+  - Docker: `docker.io` + `docker-compose` + add user to `docker` group, or Docker CE repo.
+- [ ] Update `main-setup.sh` gate accordingly.
+
+### `scripts/04-config-symlinks.sh`
+- [ ] No functional changes needed (pure symlinking). Optionally handle `~/.bash_aliases` (Debian's default bashrc sources it) or leave as-is since `bashrc` sources `aliases.bash` directly.
+
+### Shell rc files (`bashrc`, `zshrc`, aliases)
+- [ ] Already distro-agnostic (PATH for `/usr/local/go`, `~/.local/bin`, cargo, nvm). No Fedora-specific bits.
+- [ ] Note: `zshrc` still references **oh-my-zsh** (`$ZSH/oh-my-zsh.sh`, `plugins=(git)`) but no script installs it anymore (repo moved to Oh-My-Posh). On a fresh Debian this will fail silently. Decide: purge oh-my-zsh remnants or restore its install step. Recommend purging on this branch.
+- [ ] Ensure `~/.fzf.zsh` / `~/.fzf.bash` generation (`fzf --zsh`/`--bash`) or skip gracefully (already guarded).
+
+### `README.md`
+- [ ] Update "Supported Distributions" / feature matrix to reflect **Debian 13 = first-class**, Fedora optional.
+- [ ] Rename "Fedora-Specific (.NET)" section → ".NET Development" with per-distro notes.
+- [ ] Update post-install steps (group names `docker`, `libvirt`; remove Fedora-only log-out note if not applicable; add PEP 668 note).
+- [ ] Update file listing for `03-*.sh` renames.
+
+---
+
+## 4. Open decisions (need your input)
+
+1. **Container runtime on Debian:** `docker.io` (Debian pkg) vs official **Docker CE** repo vs **Podman** (since Fedora used Podman Desktop + `moby-engine`)? This repo mixes docker aliases and Podman Desktop flatpak.
+2. **VS Code source:** keep **Flatpak** `com.visualstudio.code` (already in list) or switch to MS apt repo `.deb` like Fedora's RPM setup did?
+3. **.NET SDK version to target:** repo tries 8.0 → 9.0 on Fedora; pick a default for Debian (e.g. SDK 10 on trixie) or keep the fallback loop.
+4. **oh-my-zsh remnants in `zshrc`:** purge (recommended) or keep?
+5. **Scope of this branch:** full rework of all scripts, or a lighter pass (fix names + PEP 668 + .NET script) to validate on a live trixie box first?
+
+---
+
+## 5. Suggested execution order
+
+1. Do the cheap, high-confidence fixes:
+   - `main-setup.sh` gating + `.NET` prompt
+   - `01-package-install.sh` Debian package renames (`bind9-dnsutils`, `bat` symlink, prerequisites, virt stack)
+   - `02-dev-tools-setup.sh` PEP 668 pynvim fix
+2. Rename/generalize `03-fedora-dotnet-setup.sh` → `03-dotnet-setup.sh`.
+3. Add upstream repo/bootstrap logic for `gh`, `terraform`, `kubectl`, `minikube`, `k9s`.
+4. Purge oh-my-zsh remnants from `zshrc`.
+5. Update `README.md`.
+6. Test end-to-end on a Debian 13 VM (or real install) before merging to `master`.
+
+---
+
+## 6. Verification checklist (on Debian 13)
+
+```bash
+# sanity
+cat /etc/os-release            # expect ID=debian, VERSION_CODENAME=trixie
+./main-setup.sh                # expect "Using Package Manager: apt"
+bat --version                  # symlink check
+fd --version                   # symlink check
+dig example.com                # bind9-dnsutils
+python3 -m pip install --user pynvim   # must not hit PEP 668 error
+dotnet --list-sdks
+docker ps                      # group membership
+virsh list                     # libvirt group
+```