# DotFiles

Master repo for a Hyprland desktop on Arch Linux. Dotfiles are organized as
[GNU Stow](https://www.gnu.org/software/stow/) packages (one top-level dir
per app, mirroring `$HOME`), and an interactive TypeScript CLI drives
package installation, symlinking, updates, and removal.

## Prerequisites

```
sudo pacman -S --needed stow nodejs npm
```
(`yay` is bootstrapped automatically by `install` if missing.)

## Usage

```
npm install
npm start install   # interactive: choose packages, installs them, backs up
                     # conflicting files, symlinks dotfiles into $HOME
npm start update     # pacman -Syu + yay -Syu, then re-links any new files
npm start remove     # removes symlinks, restores the most recent backup
                      # (does NOT uninstall packages)
```

Backups of any pre-existing files that would have collided with a symlink
are stored at `~/.dotfiles-backup/<timestamp>/`. `remove` restores the most
recent one automatically; to restore an older one manually:

```
cp -a ~/.dotfiles-backup/<timestamp>/. ~/
```

Which packages/dirs were chosen at install time is recorded in
`~/.config/dotfiles/state.json`, so `update`/`remove` know what to act on
without re-prompting.

`install` also installs SDDM and enables its systemd service (so Hyprland
actually starts at next boot), and auto-detects installed GPU(s) via `lspci`
to propose NVIDIA/AMD/Intel driver packages (confirm/override before they're
installed). If NVIDIA is kept, the required Wayland env vars are written to
`~/.config/hypr/confd/nvidia.lua` (machine-generated, not stowed) and
sourced from `hyprland.lua`.

## Wallpaper

Default wallpaper by rahremix (via github.com/PsychedelicPalimpsest/dotfiles).

## Adding a new app

Add a directory under `packages/` mirroring its `$HOME` layout (e.g.
`packages/foo/.config/foo/config`), and add an entry to `src/packages.ts` with the
matching package `name` (and `dir` if it differs, or a `group` if it's a
mutually-exclusive alternative to another package).

## Testing in a container

`./docker/test.sh` runs a disposable Arch container with `stow`/`nodejs`/`npm`
preinstalled and the repo copied in, without touching the host:

```
./docker/test.sh                        # interactive shell, deps installed
./docker/test.sh "npx tsc --noEmit"     # run one command non-interactively
```

## Testing in a VM

The container above can't run a graphical Hyprland session (no display, no
GPU). To actually see a config change before installing it on a real machine,
boot an Arch Linux VM (QEMU/KVM, virt-manager, or whatever you're used to —
there's no scripted provisioning for this, it's a manual one-off):

1. Get the repo into the VM (shared folder, `git clone`, `scp`, whatever's
   convenient), then `sudo pacman -Syu && npm install && npm start install`,
   choosing `hyprland` + `hyprpaper` + a bar.
2. Reboot into SDDM and log into Hyprland.
3. From a terminal in that session, use `hyprctl` to inspect/validate config
   live — `hyprctl reload`, `hyprctl monitors`, `hyprctl keyword <name> <value>`,
   `hyprctl dispatch <dispatcher> <args>` — instead of editing-and-relaunching
   blindly. See the [hyprctl wiki page](https://wiki.hypr.land/Configuring/Advanced-and-Cool/Using-hyprctl/)
   for the full command set, including its interactive REPL mode.