# Moonarch

Reproducible Arch Linux desktop environment — fully automated from bare metal to a
configured Niri (scrollable tiling Wayland) system with Catppuccin Mocha theming.

Moonarch combines archinstall for the base system with post-install automation that
handles packages, XDG defaults, system services, greeter, idle management, and a
Walker launcher with native providers and dmenu-based helper scripts. The result is a complete development/productivity
desktop that can be rebuilt from scratch in minutes.

## Why These Choices

| Component | Choice | Why |
|-----------|--------|-----|
| **Compositor** | [Niri](https://github.com/YaLTeR/niri) | Scrollable tiling — no fixed grid, infinite horizontal workspace. Purpose-built Wayland compositor, not an X11 port. |
| **Greeter** | [greetd](https://sr.ht/~kennylevinsen/greetd/) + [moongreet](https://gitea.moonarch.de/nevaforget/moongreet) | Minimal, Wayland-native login. moongreet provides GTK4 UI with fingerprint support, running inside its own Niri instance. |
| **Lock Screen** | [moonlock](https://gitea.moonarch.de/nevaforget/moonlock) | ext-session-lock-v1 protocol — compositor guarantees lock on crash. PAM + fprintd, GPU blur, multi-monitor. |
| **Power Menu** | [moonset](https://gitea.moonarch.de/nevaforget/moonset) | GTK4 Layer Shell overlay above Waybar. Lock, logout, hibernate, reboot, shutdown with confirmation. |
| **Idle Manager** | [stasis](https://aur.archlinux.org/packages/stasis) | Separate AC/battery power plans. Brightness dimming, DPMS, lock (via moonlock), and suspend on configurable timeouts. |
| **Bar** | [Waybar](https://github.com/Alexays/Waybar) | Wayland-native, highly customizable. Niri workspace/window modules via community plugins. |
| **Launcher** | [Walker](https://github.com/abenz1267/walker) + [Elephant](https://github.com/abenz1267/elephant) | Wayland-native GTK4 launcher with built-in providers for apps, clipboard, bluetooth, audio, files, and calculator. Dmenu mode for custom scripts (VPN, CPU governor). |
| **Terminal** | [Foot](https://codeberg.org/dnkl/foot) | Fast, minimal Wayland-native terminal. Server mode for instant window spawning. |
| **Shell** | Zsh | Programmable completion, FZF integration, syntax highlighting. |
| **Audio** | PipeWire | Drop-in replacement for PulseAudio/JACK with lower latency. RNNoise input denoising configured out of the box. |
| **Display Management** | [kanshi](https://sr.ht/~emersion/kanshi/) + [wdisplays-persistent](https://github.com/sfs-pra/wdisplays) | kanshi auto-switches output profiles on hotplug. wdisplays-persistent saves changes directly to kanshi config. |
| **Notifications** | [swaync](https://github.com/ErikReider/SwayNotificationCenter) | GTK4 notification daemon with DND toggle, grouping, MPRIS support. Fractional scaling via native GTK4. |
| **Clipboard** | [cliphist](https://github.com/sentriz/cliphist) + Walker | Clipboard history stored in runtime dir, wiped on session start. Walker provides the picker UI. |
| **GTK Theme** | Colloid-Grey-Dark-Catppuccin | Catppuccin Mocha palette, grey accent, explicit dark variant. |
| **Icons** | Colloid-Grey-Catppuccin-Dark | Catppuccin-colored icon set matching the GTK theme. |
| **Cursor** | Sweet-cursors | Visible on dark backgrounds without clashing. |
| **Font** | UbuntuSans Nerd Font | Clean sans-serif with full Nerd Font glyph coverage for bar/terminal icons. |
| **Wallpaper** | [waypaper](https://github.com/anufrievroman/waypaper) + [awww](https://codeberg.org/LGFae/awww) | waypaper provides GUI selection, awww handles animated transitions (60 FPS, 2s crossfade). |
| **Night Light** | [wlsunset](https://sr.ht/~kennylevinsen/wlsunset/) | Wayland-native blue light filter via wlr-gamma-control. Toggleable from Waybar brightness group. |
| **Firewall** | UFW | Simple deny-incoming/allow-outgoing default. Sane baseline without iptables complexity. |
| **AUR Helper** | [paru](https://github.com/Morganamilo/paru) | Rust-based, pacman-compatible. Supports custom PKGBUILD repos for moongreet/moonlock/moonset. |

## Quick Start

### Fresh Install (Bare Metal)

1. Boot the [Arch ISO](https://archlinux.org/download/) and download the config:
   ```bash
   curl -O https://gitea.moonarch.de/nevaforget/moonarch/raw/branch/main/config/user_configuration.json
   archinstall --config user_configuration.json
   ```
2. Choose disk and kernel interactively — everything else comes from the config.
3. Reboot, log in, then:
   ```bash
   /opt/moonarch/scripts/post-install.sh
   ```
4. Reboot again — done.

The archinstall config clones this repo to `/opt/moonarch` via custom-commands.
post-install.sh handles the remaining ~95 packages, all configs, themes, services,
and user setup.

### Transform (Existing Arch+Wayland System)

Already running Arch with a Wayland compositor (Sway, Hyprland, GNOME Wayland, etc.)?
Transform converts your system to Moonarch without reinstalling.

**Prerequisites:** Active Wayland session, git installed.

```bash
# Clone the repo
sudo git clone https://gitea.moonarch.de/nevaforget/moonarch.git /opt/moonarch

# Preview what will happen (no changes made)
/opt/moonarch/scripts/transform.sh --dry-run

# Run the transform
/opt/moonarch/scripts/transform.sh

# Reboot (do NOT log out — your previous DM is already disabled)
sudo reboot
```

The script will:
1. Show a pre-flight summary (package diff, config changes, detected conflicts)
2. Back up your `~/.config/`, `~/.zshrc`, and `/etc/xdg/` to timestamped tar archives
3. Disable conflicting display managers (SDDM, GDM, LightDM, etc.)
4. Remove conflicting packages (e.g. PulseAudio → PipeWire)
5. Install all Moonarch packages and configs (**hard overwrite** of most user configs; kanshi display profiles are preserved)
6. Enable greetd, firewall, and system services

### Update

```bash
moonarch-update
```

Interactive updater that upgrades system and AUR packages, reconciles package lists
against what's installed, and cleans orphaned packages. Config deployment happens
automatically via the moonarch-git package on `paru -Syu`.

## Project Structure

```
config/
  user_configuration.json       archinstall config (locale, audio, services, custom-commands)

packages/
  official.txt                  Arch repo packages (~80), one per line
  aur.txt                       AUR packages (~20), one per line

scripts/
  lib.sh                        Shared helpers sourced by all scripts
  post-install.sh               Main automation (packages, configs, themes, services)
  transform.sh                  Convert existing Arch+Wayland system to Moonarch
  moonarch-update               Interactive updater (deployed to /usr/bin/ by package)

defaults/
  xdg/                          System-wide XDG configs (deployed to /etc/xdg/)
    niri/config.kdl               Compositor: layout, keybinds, startup apps
    waybar/config, style.css      Bar: modules, layout, Catppuccin styling
    walker/config.toml, themes/   Launcher: Walker config + moonarch theme (Catppuccin Mocha)
    foot/foot.ini                 Terminal: font, colors, keybinds
    swaync/config.json, style.css Notifications: appearance, behavior, MPRIS
    kanshi/config                 Display profiles (empty seed, user-configured via wdisplays)
    stasis/stasis.rune            Idle manager: AC/battery power plans
    pipewire/                     Audio: RNNoise input denoising
    waypaper/config.ini           Wallpaper manager: backend, folder, transitions
    fastfetch/config.jsonc        System info display
    gtk-3.0/, gtk-4.0/           GTK theme settings

  bin/                          Helper scripts (deployed to /usr/bin/)
    moonarch-sink-switcher        Audio output switcher (walker dmenu + pactl)
    moonarch-vpn                  VPN connection manager (walker dmenu + nmcli)
    moonarch-cpugov               CPU governor switcher (walker dmenu + auto-cpufreq)
    moonarch-btnote               Bluetooth device battery monitor (upower + notify-send)
    moonarch-capsnote             Caps Lock toggle notification
    moonarch-waybar-cpugov        Waybar module: CPU governor status
    moonarch-waybar-gpustat       Waybar module: GPU utilization
    moonarch-waybar-hidpp         Waybar module: Logitech HID++ device battery
    moonarch-waybar-batsaver      Waybar module: battery conservation mode indicator
    moonarch-waybar-updates       Waybar module: package update checker (repo + AUR)
    moonarch-batsaver-toggle      Toggle battery charge limit (80% ↔ 100%)
    moonarch-nightlight           Toggle wlsunset blue light filter on/off
    moonarch-waybar-nightlight    Waybar module: nightlight status

  shell/zshrc                   Zsh config: prompt, aliases, FZF, completion
  etc/greetd/                   greetd daemon + greeter Niri config
  etc/moongreet/                moongreet configuration
  etc/systemd/user/             Systemd user services (cliphist, kanshi, walker, nautilus)
  etc/systemd/system/           System service (battery conservation restore on boot)
  etc/udev/rules.d/             udev rules (battery threshold permissions)
  backgrounds/wallpaper.jpg     Default wallpaper (shared by desktop, greeter, lock screen)
```

## Startup Sequence

```
greetd ─► niri (greeter instance) ─► moongreet ─► user authenticates
                                                         │
                                                         ▼
                                                   niri (user session)
                                                         │
                           ┌──────────┬────────┬────────┬──────────┐
                           ▼          ▼        ▼        ▼          ▼
                        waybar     swaync   foot     waypaper   nm-applet  wlsunset
                        (bar)    (notify) (server)  (wallpaper)  (VPN)    (nightlight)

                        systemd user services (graphical-session.target):
                        kanshi, cliphist, walker, nautilus
```

## Keybinds (Default)

| Key | Action |
|-----|--------|
| `Super+Return` | Open terminal (foot) |
| `Super+Space` | App launcher (walker) |
| `Super+Q` | Close window |
| `Super+O` / `Super+Tab` | Overview |
| `Super+F` | Maximize column |
| `Super+Shift+F` | Fullscreen window |
| `Super+V` | Toggle floating |
| `Super+H/J/K/L` | Focus left/down/up/right |
| `Super+Ctrl+H/J/K/L` | Move window |
| `Super+Shift+H/J/K/L` | Focus monitor |
| `Super+1-9` | Switch workspace |
| `Super+C` | Clipboard history |
| `Super+E` | File manager |
| `Super+A` | Audio control (walker) |
| `Super+N` | VPN manager |
| `Mod+Escape` | Session menu (moonset) |
| `Print` | Screenshot |
| `Ctrl+Print` | Screenshot screen |
| `Alt+Print` | Screenshot window |

## Customization

All system configs live in `/etc/xdg/` and can be overridden per-user in `~/.config/`:

| Component | System Default | User Override |
|-----------|---------------|---------------|
| Niri | `/etc/xdg/niri/config.kdl` | `~/.config/niri/config.kdl` |
| Waybar | `/etc/xdg/waybar/` | `~/.config/waybar/` |
| Walker | `/etc/xdg/walker/` | `~/.config/walker/` |
| Foot | `/etc/xdg/foot/foot.ini` | `~/.config/foot/foot.ini` |
| swaync | `/etc/xdg/swaync/` | `~/.config/swaync/` |
| kanshi | `/etc/xdg/kanshi/config` | `~/.config/kanshi/config` |
| PipeWire | `/etc/xdg/pipewire/` | `~/.config/pipewire/` |
| Zsh | `/etc/zsh/zshrc.moonarch` | `~/.zshrc` + `~/.zshrc.d/` |

Helper scripts in `/usr/bin/moonarch-*` are not meant to be overridden — they
are part of the system and updated via `paru -Syu`.

## System Services

| Service | Purpose |
|---------|---------|
| greetd | Login greeter (runs moongreet inside Niri) |
| NetworkManager | Network management (WiFi, VPN, Ethernet) |
| bluetooth | Bluetooth stack (bluez) |
| systemd-timesyncd | NTP time synchronization |
| ufw | Firewall (deny incoming, allow outgoing) |
| auto-cpufreq | CPU frequency scaling (AC: performance, battery: powersave) |

### User Services (systemd --user)

| Service | Purpose |
|---------|---------|
| cliphist | Clipboard history (wipes on session start, stores in runtime dir) |
| kanshi | Dynamic display configuration (auto-switch output profiles on hotplug) |
| nautilus | File manager preload (faster first launch) |
| stasis | Idle manager (dimming, DPMS, lock, suspend on AC/battery plans) |
| walker | Walker application launcher (GTK4 service mode for instant startup) |

## Moonarch Ecosystem

Moonarch is the deployment and configuration layer. Three companion projects provide
the Wayland session UI — all built with Rust + gtk4-rs and sharing Catppuccin Mocha
theming:

| Project | Role | Installed via |
|---------|------|---------------|
| [moongreet](https://gitea.moonarch.de/nevaforget/moongreet) | greetd greeter (GTK4 Layer Shell, fingerprint, i18n) | `paru -S moongreet-git` |
| [moonlock](https://gitea.moonarch.de/nevaforget/moonlock) | Wayland lock screen (ext-session-lock-v1, PAM, fprintd) | `paru -S moonlock-git` |
| [moonset](https://gitea.moonarch.de/nevaforget/moonset) | Power menu overlay (GTK4 Layer Shell) | `paru -S moonset-git` |

These are built from a [custom paru package repository](https://gitea.moonarch.de/nevaforget/moonarch-pkgbuilds)
added during post-install.

## License

MIT