diff --git a/docs/superpowers/plans/2026-05-25-hyprlock-replace-gtklock.md b/docs/superpowers/plans/2026-05-25-hyprlock-replace-gtklock.md new file mode 100644 index 0000000..986c62f --- /dev/null +++ b/docs/superpowers/plans/2026-05-25-hyprlock-replace-gtklock.md @@ -0,0 +1,439 @@ +# Replace gtklock with hyprlock Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Swap the lockscreen from `gtklock` to `hyprlock` so fingerprint unlock works without typing a character first. + +**Architecture:** Replace one tracked config tree (`gtklock/`) with another (`hyprlock/`). Update `packages.txt`, `install.sh`, `niri/config.kdl`, `scripts/enable-fingerprint.sh`, and docs. The user re-runs `install.sh` + `enable-fingerprint.sh` after merge. + +**Tech Stack:** Hyprlang config, niri, bash, PAM. + +**Spec:** `docs/superpowers/specs/2026-05-25-hyprlock-replace-gtklock-design.md` + +**Verification model:** `niri validate` for niri changes, `bash -n` for shell, parse-check for the Hyprlang config (`hyprlock --help` won't validate config without `-c`; spec-correctness is via inspection). Functional end-to-end (touch reader → unlock) is interactive — controller verifies after the live install + bootstrap. + +--- + +## File Structure + +| File | Role | +|---|---| +| `hyprlock/hyprlock.conf` | New — single Hyprlang file, deployed to `~/.config/hypr/hyprlock.conf` | +| `packages.txt` | swap `gtklock` → `hyprlock`, drop `gtklock-userinfo-module` if present | +| `install.sh` | drop gtklock symlinks + the `gtklock` mkdir entry, add hyprlock symlink | +| `niri/config.kdl` | swap 3 gtklock invocations (Mod+Shift+E + 2 swayidle) | +| `scripts/enable-fingerprint.sh` | swap target in `TARGETS` array | +| `gtklock/config.ini`, `gtklock/style.css` | deleted | +| `README.md`, `ARCHITECTURE.md`, `CLAUDE.md` | swap lockscreen references | + +5 tasks, each atomic. + +--- + +## Task 1: Add `hyprlock` config + swap `install.sh` + `packages.txt` + +After this task: `hyprlock` is in `packages.txt`, `hyprlock/hyprlock.conf` exists, `install.sh` symlinks it into `~/.config/hypr/` (mkdir-ing the dir if needed), and the gtklock symlinks are gone from `install.sh`. The repo still has `gtklock/` files and niri still calls gtklock — Tasks 2-4 finish the swap. + +**Files:** +- Create: `hyprlock/hyprlock.conf` +- Modify: `packages.txt` +- Modify: `install.sh` (lines 19, 43-44) + +- [ ] **Step 1: Create `hyprlock/hyprlock.conf`** + +```bash +mkdir -p hyprlock +``` + +Write `hyprlock/hyprlock.conf` with this exact content: + +```hyprlang +general { + grace = 0 + hide_cursor = true +} + +background { + monitor = + path = screenshot + blur_passes = 3 + blur_size = 8 +} + +label { + monitor = + text = cmd[update:1000] date +"%-I:%M %p" + font_size = 96 + color = rgba(c5c8c6ff) + position = 0, 150 + halign = center + valign = center +} + +label { + monitor = + text = cmd[update:60000] date +"%A, %B %-d" + font_size = 24 + color = rgba(969896ff) + position = 0, 40 + halign = center + valign = center +} + +input-field { + monitor = + size = 300, 50 + outline_thickness = 2 + dots_size = 0.25 + dots_spacing = 0.4 + inner_color = rgba(282a2eff) + outer_color = rgba(81a2beff) + font_color = rgba(c5c8c6ff) + fail_color = rgba(cc6666ff) + check_color = rgba(b5bd68ff) + placeholder_text = Touch fingerprint or type password + fail_text = $FAIL + fade_on_empty = false + position = 0, -50 + halign = center + valign = center +} +``` + +- [ ] **Step 2: Update `packages.txt`** + +Currently `gtklock` is on line 13 (between `pamixer` and `swayidle`): +``` +gtklock +swayidle +``` + +Replace `gtklock` with `hyprlock`: +``` +hyprlock +swayidle +``` + +If `gtklock-userinfo-module` appears anywhere in the file, also delete that line. Verify with: +```bash +grep -E "gtklock" packages.txt +``` +Expected: zero matches after edit. + +```bash +grep -c "^hyprlock$" packages.txt +``` +Expected: `1`. + +- [ ] **Step 3: Update `install.sh` — remove gtklock symlinks and entry, add hyprlock symlink** + +Find lines 43-44: +```bash +ln -sf "$(pwd)/gtklock/config.ini" ~/.config/gtklock/config +ln -sf "$(pwd)/gtklock/style.css" ~/.config/gtklock/style.css +``` + +Replace both lines with: +```bash +mkdir -p ~/.config/hypr +ln -sf "$(pwd)/hyprlock/hyprlock.conf" ~/.config/hypr/hyprlock.conf +``` + +Also find line 19 (the brace-expansion mkdir): +```bash +mkdir -p ~/.config/{niri,waybar,wofi,mako,alacritty,gtk-3.0,gtk-4.0,gtklock,fish} ~/.config/environment.d ~/.config/xdg-desktop-portal +``` + +Remove `gtklock,` from the brace list (no need to mkdir gtklock anymore): +```bash +mkdir -p ~/.config/{niri,waybar,wofi,mako,alacritty,gtk-3.0,gtk-4.0,fish} ~/.config/environment.d ~/.config/xdg-desktop-portal +``` + +- [ ] **Step 4: Bash-syntax-check install.sh** + +```bash +bash -n install.sh && echo "syntax ok" +``` + +Expected: `syntax ok`, exit 0. + +- [ ] **Step 5: Confirm changes landed** + +```bash +grep -nE "gtklock|hyprlock" install.sh +``` + +Expected: 2 hits — both for hyprlock (`mkdir -p ~/.config/hypr` and the `ln -sf ... hyprlock.conf` line). No `gtklock` references remain. + +```bash +ls hyprlock/hyprlock.conf && wc -l hyprlock/hyprlock.conf +``` + +Expected: file exists, ~52 lines. + +- [ ] **Step 6: Commit** + +```bash +git add hyprlock/hyprlock.conf packages.txt install.sh +git commit -m "hyprlock: add config + swap install.sh away from gtklock" +``` + +--- + +## Task 2: Swap niri keybind + swayidle hooks from gtklock to hyprlock + +After this task, niri's lock keybind and swayidle's lock-on-idle/before-sleep hooks all call `hyprlock` instead of `gtklock -d`. The repo still has the `gtklock/` config files and the old PAM target in `enable-fingerprint.sh` — Tasks 3-4 finish those. + +**Files:** +- Modify: `niri/config.kdl` + +- [ ] **Step 1: Find the three gtklock invocations** + +```bash +grep -n "gtklock" niri/config.kdl +``` + +Expected: 3 matches — one in the swayidle `spawn-at-startup` line (with two `"gtklock" "-d"` substrings — counts as the same line, may show twice if grep prints once per line), and one keybind line `Mod+Shift+E { spawn "gtklock" "-d"; }`. + +- [ ] **Step 2: Replace the keybind** + +Find `Mod+Shift+E { spawn "gtklock" "-d"; }` and replace with: +```kdl + Mod+Shift+E { spawn "hyprlock"; } +``` + +Indentation: 4 spaces, matching the surrounding `binds` block entries. + +- [ ] **Step 3: Replace the swayidle line's two `"gtklock" "-d"` occurrences** + +The swayidle spawn-at-startup line looks like: +```kdl +spawn-at-startup "swayidle" "-w" "timeout" "300" "niri msg action power-off-monitors" "timeout" "600" "gtklock" "-d" "timeout" "1800" "systemctl suspend-then-hibernate" "before-sleep" "gtklock" "-d" +``` + +Replace both `"gtklock" "-d"` substrings with `"hyprlock"`. The full line becomes: +```kdl +spawn-at-startup "swayidle" "-w" "timeout" "300" "niri msg action power-off-monitors" "timeout" "600" "hyprlock" "timeout" "1800" "systemctl suspend-then-hibernate" "before-sleep" "hyprlock" +``` + +Note: each `"gtklock" "-d"` (two quoted strings, two niri spawn args) becomes a single `"hyprlock"` (one quoted string). + +- [ ] **Step 4: Validate niri config** + +```bash +niri validate 2>&1 | tail -2 +``` + +Expected: a final `INFO niri: config is valid`. Exit 0. + +- [ ] **Step 5: Confirm gtklock is gone, hyprlock present** + +```bash +grep -c "gtklock" niri/config.kdl +grep -c "hyprlock" niri/config.kdl +``` + +Expected: `0` for gtklock, `3` for hyprlock (one keybind + two swayidle action positions). + +- [ ] **Step 6: Commit** + +```bash +git add niri/config.kdl +git commit -m "niri: switch lock + idle hooks to hyprlock" +``` + +--- + +## Task 3: Update `scripts/enable-fingerprint.sh` PAM target + +After this task, re-running the script targets `/etc/pam.d/hyprlock` instead of `/etc/pam.d/gtklock`. The existing line in `/etc/pam.d/gtklock` is left in place on the live system (harmless dead config — see Out of Scope in the spec). + +**Files:** +- Modify: `scripts/enable-fingerprint.sh` (one line in the `TARGETS` array) + +- [ ] **Step 1: Find the TARGETS line** + +```bash +grep -n "TARGETS" scripts/enable-fingerprint.sh +``` + +Expected: one line like: +``` +TARGETS=(/etc/pam.d/sudo /etc/pam.d/gtklock) +``` + +- [ ] **Step 2: Replace `gtklock` with `hyprlock`** + +Change the line to: +```bash +TARGETS=(/etc/pam.d/sudo /etc/pam.d/hyprlock) +``` + +- [ ] **Step 3: Syntax-check** + +```bash +bash -n scripts/enable-fingerprint.sh && echo "syntax ok" +``` + +Expected: `syntax ok`, exit 0. + +- [ ] **Step 4: Confirm the swap** + +```bash +grep -n "gtklock\|hyprlock" scripts/enable-fingerprint.sh +``` + +Expected: one match — the new `hyprlock` line. Zero `gtklock` references. + +- [ ] **Step 5: Commit** + +```bash +git add scripts/enable-fingerprint.sh +git commit -m "scripts: enable-fingerprint targets hyprlock PAM file" +``` + +--- + +## Task 4: Delete the tracked `gtklock/` directory + +After this task, the repo no longer carries `gtklock/config.ini` or `gtklock/style.css`. The system's `/etc/pam.d/gtklock` (with the harmless dead pam_fprintd line) is untouched. The user's `~/.config/gtklock/` symlinks become broken but harmless since gtklock is no longer launched. + +**Files:** +- Delete: `gtklock/config.ini` +- Delete: `gtklock/style.css` + +- [ ] **Step 1: Remove the tracked files** + +```bash +git rm gtklock/config.ini gtklock/style.css +``` + +Expected output: +``` +rm 'gtklock/config.ini' +rm 'gtklock/style.css' +``` + +The empty `gtklock/` directory may remain — git ignores empty directories. If it bothers you cosmetically, `rmdir gtklock` to clean up. + +- [ ] **Step 2: Confirm no references remain in the repo (outside docs)** + +```bash +grep -rn "gtklock" --exclude-dir=.git --exclude-dir=docs --exclude-dir=.claude /home/alex/Documents/dotfiles +``` + +Expected: only matches in README.md, ARCHITECTURE.md, CLAUDE.md (those get updated in Task 5). No matches in install.sh, niri/, scripts/, packages.txt, or the deleted `gtklock/` directory. + +- [ ] **Step 3: Commit** + +```bash +git commit -m "gtklock: delete tracked config (replaced by hyprlock)" +``` + +(`git rm` already staged the deletions; no further `git add` needed.) + +--- + +## Task 5: Update README, ARCHITECTURE, CLAUDE.md + +After this task, all documentation references `hyprlock` instead of `gtklock`. + +**Files:** +- Modify: `README.md` +- Modify: `ARCHITECTURE.md` +- Modify: `CLAUDE.md` + +- [ ] **Step 1: Find every gtklock reference in the three docs** + +```bash +grep -n "gtklock" README.md ARCHITECTURE.md CLAUDE.md +``` + +Expected: a small handful of matches. Most are in tooling tables (`| Lockscreen | gtklock |`) and short narrative mentions. + +- [ ] **Step 2: README.md — replace each gtklock occurrence with hyprlock** + +For each line `grep` returned in README.md, change `gtklock` → `hyprlock`. Most likely: +- A tooling table row: `| Lockscreen | gtklock |` → `| Lockscreen | hyprlock |` +- The `Mod+Shift+E` mention in the fingerprint setup section, if it referenced gtklock by name (verify against the actual line — it may already be `Mod+Shift+E to lock` without naming the lockscreen) + +For each match, use `sed -i 's/gtklock/hyprlock/g' README.md` if every occurrence should change verbatim, or hand-edit if context requires more thought (rare for this kind of swap). + +Verify after: +```bash +grep -n "gtklock" README.md +``` +Expected: zero matches. + +```bash +grep -c "hyprlock" README.md +``` +Expected: matches the count from Step 1 (1-for-1 replacement). + +- [ ] **Step 3: ARCHITECTURE.md — same swap** + +```bash +sed -i 's/gtklock/hyprlock/g' ARCHITECTURE.md +grep -n "gtklock" ARCHITECTURE.md +``` + +Expected: zero matches. + +- [ ] **Step 4: CLAUDE.md — same swap** + +```bash +sed -i 's/gtklock/hyprlock/g' CLAUDE.md +grep -n "gtklock" CLAUDE.md +``` + +Expected: zero matches. + +- [ ] **Step 5: Final repo-wide sanity check** + +```bash +grep -rn "gtklock" --exclude-dir=.git --exclude-dir=docs --exclude-dir=.claude /home/alex/Documents/dotfiles +``` + +Expected: zero matches anywhere except inside `docs/` (the historical spec/plan files for the original gtklock setup) and `.claude/` (cached permission entries). + +- [ ] **Step 6: Commit** + +```bash +git add README.md ARCHITECTURE.md CLAUDE.md +git commit -m "docs: flip lockscreen references to hyprlock" +``` + +--- + +## Final verification (controller, post-merge) + +- [ ] **Install hyprlock**: +```bash +bash install.sh +which hyprlock +``` +Expected: `/usr/bin/hyprlock`. + +- [ ] **Verify config deployed**: +```bash +ls -la ~/.config/hypr/hyprlock.conf +``` +Expected: symlink to repo's `hyprlock/hyprlock.conf`. + +- [ ] **Re-run PAM bootstrap**: +```bash +sudo bash scripts/enable-fingerprint.sh +``` +Expected output mentions `/etc/pam.d/hyprlock` got the new line; `/etc/pam.d/sudo` "already present — skipping". + +- [ ] **Verify PAM line is in hyprlock**: +```bash +grep pam_fprintd /etc/pam.d/hyprlock +``` +Expected: one match. + +- [ ] **Functional tests**: +1. `Mod+Shift+E` — locks the screen with clock + date + input field. +2. Touch the fingerprint reader (without typing anything) — unlocks immediately. +3. Re-lock; type the password instead — also unlocks (fallback). +4. Wait 10 min idle — swayidle triggers `hyprlock` automatically.