test suite with docker container and linter

README.md

@@ -9,7 +9,9 @@ Personal configuration files for an Arch Linux workstation (Hyprland + Neovim +
 | `term/`    | Fish + kitty + starship + nvim + tmux + yazi + fastfetch + opencode terminal environment |
 | `hypr/`    | Hyprland compositor config, kitty theme, wpaperd wallpapers |
 | `kreation/`| VST plugin (`MT-PowerDrumKit.vst3`) |
+| `local_ai/`| Local AI / MCP tooling config |
 | `_install_skripte/` | Miscellaneous install helper scripts |
+| `test/`    | Docker test harness (lint + smoke tests) |
 
 Each top-level directory is a **stow package**. `stow` symlinks the files from the repository into your home directory (e.g. `term/.config/...` → `~/.config/...`).
 
@@ -125,4 +127,56 @@ stow --ignore='\.config/(local|misc)' term
 
 ---
 
+## Testing
+
+The `test/` directory contains a Docker-based test harness that verifies the
+install scripts, the `Makefile`, and the stow packages.
+
+There are **two tiers**:
+
+| Target | What it does | Docker required? |
+|--------|--------------|------------------|
+| `make test-lint` | Fast, offline integrity checks: `bash -n` syntax pass over every script, `shellcheck` (if installed), `packages.txt` marker validation, and Makefile ↔ script/stow-package name consistency. Catches typos like `_install_skripte_install_basic_pcks.sh` (missing `/`). | No |
+| `make test-stow` | `stow --simulate` for every stow-able package; fails if a package the Makefile stows doesn't exist (e.g. `stow nvim` — nvim lives under `term/`). | No |
+| `make test-shellcheck` | Runs shellcheck over all tracked scripts (shellcheck must be installed). | No |
+| `make test-lint-docker` | Builds the `/dev` stage (`archlinux:latest` + shellcheck) and runs `test/lint.sh` inside it. | Yes |
+| `make test-smoke` | Builds the `/test` stage and runs the container's dry probes: `make -n` over every target, `stow --simulate` over every Makefile-stowed package, plus `test/lint.sh`. A network-enabled `RUN_SMOKE=1` variant installs the real pacman packages. | Yes |
+| `make test` | `test-lint` + `test-smoke`. | Partially |
+
+### Docker smoke details
+
+```bash
+make test-smoke                     # dry probes only (fast, no installs)
+make test-smoke RUN_SMOKE=1         # + real pacman installs of the term packages
+make test-smoke RUN_SMOKE=1 RUN_FULL=1   # + AUR/npm + hypr/kreation/buntes-monster
+make test-smoke SKIP_NET=1          # skip anything that contacts the network
+```
+
+The container:
+
+- uses `archlinux:latest` (the scripts assume Arch + pacman),
+- creates a non-root user (`mathias`, uid 1000) with passwordless sudo so the
+  scripts don't hang on a password prompt,
+- mounts the live repo at `/dotfiles` (`-v "$PWD":/dotfiles`), so the tests
+  always run against your current checkout,
+- stubs host daemon commands (`systemctl`, `updatedb`, `kbuildsycoca6`,
+  `dbus-update-activation-environment`) as no-ops so nothing talks to a real
+  systemd/dbus inside the container.
+
+In the `RUN_SMOKE=1` install path, the harness additionally **verifies the
+installed packages** (`test/verify_packages.sh`):
+- every `@pacman` entry is confirmed via `pacman -Q <pkg>` (covers fonts,
+  libs and python modules that ship no binary),
+- a curated mapping probes each package's binary with a real
+  `--version`-style call (e.g. `fish --version`, `nvim --version`,
+  `ssh -V`), failing if the binary is missing or does not report a version.
+
+> **Note for the current repo state:** `make test-lint` and `make test-smoke`
+> currently **fail** because the harness surfaces pre-existing Makefile bugs
+> (missing `/` in the `install_*` script paths and `stow nvim` for a
+> non-existent `nvim/` package). That is the intended behaviour — fix the
+> Makefile and the tests should go green.
+
+---
+
 **When in doubt:** run `stow --verbose --simulate <target>` first — it prints what would happen (linking) without changing anything. Never `rm -rf` the `~/.config` of something you still want to keep; move it to a backup directory instead.