# Dotfiles

Personal configuration files for an Arch Linux workstation (Hyprland + Neovim + VST plugin), managed with [GNU Stow](https://www.gnu.org/software/stow/).

## Layout

| Directory | Contents |
|-----------|----------|
| `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/...`).

## Prerequisites

- Arch Linux (or a distro with `pacman`)
- [`stow`](https://www.gnu.org/software/stow/)
- Relies on `git`, `sudo`, `curl`

## Quick start

```bash
# 1. Clone the repo
git clone https://github.com/<user>/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# 2. Install a target and symlink its files
make term       # terminal + fish + kitty + nvim
make hypr       # Hyprland (also pulls in basic + term)
make kreation   # VST plugin (also pulls in basic)
```

Run `make <target>` from the repository root. Each target first runs the relevant install script and then `stow`s the package.

> The install scripts require `sudo` and may prompt for your password.

## Targets

| Target | What it does |
|--------|--------------|
| `make term` | Runs `term/setup.sh` (installs terminal packages, sets fish as default shell, clones tmuxifier), then `stow term` |
| `make basic` | Runs `install_basic_pcks.sh`, stows `nvim`, runs `nextcloud.sh` |
| `make hypr`  | `make basic`, installs Hyprland packages, stows `hypr`, runs the Hyprland setup scripts (`ensure-env.sh`, `portal-host-override.sh`, `fix_dolphin_file_associations.sh`) |
| `make kreation` | `make basic`, installs VST runtime, stows `kreation` |
| `make buntes-monster` | Everything (`basic` + `hypr` + `kreation`), then wires up symlinks |

### Managing terminal packages

The terminal package list lives in a single editable file:

```
term/packages.txt
```

Add/remove packages on separate lines. Lines starting with `#` are ignored, and you can switch between package sources with section markers:

```
@pacman   # install via pacman (default)
@aur      # install via yay (AUR)
@npm      # install via npm -g
```

The default section is `@pacman`. Any AUR dependency (`yay`) is bootstrapped automatically by `term/setup.sh`.

## What the install scripts do

- **`term/setup.sh`** – enables multilib, updates the system, installs `yay` if missing, reads `term/packages.txt` and installs all packages with `--needed` (skips already-installed ones), sets `fish` as the default shell (`chsh -s /usr/bin/fish`), clones `tmuxifier`, adds the `git` yazi plugin, and runs `sudo updatedb`. It is idempotent and safe to re-run.

## Stow: resolving conflicts with existing paths

`stow` refuses to create a symlink where a real file or directory already exists on the target (your home directory). When you first set up a machine that already has configs in `~/.config`, you typically see an error like:

```
WARNING: stowing term would cause conflicts:
  * existing target is neither a link nor a directory: .config/fish/config.fish
```

The **recommended** workflow is to back up the affected paths and remove them from the target location so stow can take over, then restore anything you want to keep as an overlay on top of the symlink. There are a few common approaches:

### 1. Back up and remove (recommended for first-time setup)

Point stow elsewhere so it only *reports* conflicts without touching anything, then handle the listed paths yourself:

```bash
# Dry-run to see exactly which paths conflict
cd ~/.dotfiles
stow --verbose --simulate term

# Inspect the conflicts, then back them up on the target side
mkdir -p ~/.config-backup
mv ~/.config/fish ~/.config-backup/fish      # example — repeat for each conflicting path

# Now stow can create the links
stow term
```

Afterwards you can restore your old configs **on top of** the symlinks if you want a custom overlay:

```bash
cp -r ~/.config-backup/fish/* ~/.config/fish/
```

> The backup dir lives outside the stow packages, so stow never touches it.

### 2. Use `--adopt` with care

```bash
git stash        # only if you have uncommitted repo changes you want to keep
cd ~/.dotfiles
stow --adopt term
git checkout .   # discard any files that stow pulled into the repo
```

`stow --adopt` moves conflicting files *from your home dir into the repository* (overwriting what's stored there), then creates the symlink. This is convenient but **destructive to the repo copy** of those files — always review with a simulate run first and reset via git afterwards if you didn't intend to change the tracked config. Prefer approach #1 unless you deliberately want to recapture your live config into the repo.

### 3. Skip conflicts you don't manage in the repo

If a path simply shouldn't be managed by stow, use `--ignore`:

```bash
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.