1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
# CLAUDE.md
Guidance for AI agents working in this repo.
## What this is
`wallp` — a single bash script that sets and restores wallpapers on a fixed
two-screen wayland (sway/hyprland) setup. It merges two older scripts
(`multiwal.sh` interactive setter, `qar-lastwall.sh` restorer). Uses `swaybg` to
paint wallpapers, `qarma` for GUI selection, and `udt-accent` (the unified
desktop theme tool, outside this repo) to refresh the accent colour from the
wallpaper. `wallp` no longer runs pywal and has no theme of its own.
Logical screens are `H` (horizontal) and `V` (vertical), mapped to physical
outputs via config (`OUTPUT_H`/`OUTPUT_V`).
## Layout
- `wallp` — the whole program (one bash file, ~310 lines).
- `tests/wallp.bats` — bats test suite (the only tests).
- `wallp.conf.example` — sample config.
- `docs/superpowers/specs/` — design spec.
- `docs/superpowers/plans/` — implementation plan.
## Build / test
No build step. Run the suite:
```bash
bats tests/wallp.bats
```
Requires `bats` (1.5.0 known good). Tests run hermetically: `setup()` creates a
temp `$HOME`, stubs `swaybg`/`udt-accent`/`qarma`/`notify-send`/`pkill`/`kill` on `PATH`
(each logs its call to `$HOME/calls.log` and exits 0), then `source`s `wallp`.
The sourcing guard at EOF (`[ "${BASH_SOURCE[0]}" = "$0" ]`) keeps `main` from
running on source — **do not remove it.**
Syntax check: `bash -n wallp`.
## Development rules
- **TDD.** Every change: write the failing bats test first, confirm it fails,
implement, confirm green, commit. Functions go ABOVE `main()`.
- **Test conventions:** use `run fn` when asserting on `$status`/`$output`; call
the function directly when asserting on globals (`CONF_*`, `SET_*`) or
filesystem side effects, since `run` executes in a subshell.
- **Pure logic is unit-testable** (conf parse, arg parse, tilde expansion, output
mapping). Side-effecting bits (`swaybg`, `udt-accent`, `qarma`) are isolated in
thin functions and exercised via the PATH stubs.
- `set -u` is on. Empty-array expansion `"${set_args[@]}"` is safe on bash ≥ 4.4
(this host is fine). Guard env vars with `${VAR:-}`.
- Quote all paths (wallpaper filenames may contain spaces).
## Critical gotchas
- **Install is a symlink.** `~/bin/wallp` points at this checkout's `wallp`, so
repo edits are live immediately for the hypr autostart/keybind. No re-copy
step. (It used to be a plain copy, which shipped stale versions.)
Recreate with: `ln -sf "$PWD/wallp" ~/bin/wallp`
- **qarma `--list` needs `--radiolist --print-column=2`.** A plain `--list`
prints nothing on selection (bug that shipped once). `qarma_select` depends on
these flags; a regression test guards it.
- **qarma `--info` collapses whitespace.** Newlines and runs of spaces are eaten
by the GTK label. `show_help`'s markup uses `<br>` for line breaks and ` `
(non-breaking space) for column padding — NOT `\n` or literal spaces. Pango has
no `<br>`, but qarma preprocesses it into a newline. `--width=600` stops the
description column from wrapping (GTK still enforces a min dialog width, so the
window looks wide). The stdout branch keeps plain text; a test asserts no
markup tags leak there.
- **Selective kill.** `apply_output` kills only the changed output's swaybg PID
(tracked in `~/.cache/wallp/{H,V}.pid`). Updating one screen must never blank
the other — there's a test for this; keep it green.
- **`load_conf` return codes:** 0 ok, 1 invalid (missing required key), 10
bootstrapped (template just written → caller exits 0, no wallpaper change).
- **Persistence is wallp-owned**, under `~/.config/wallp/` (`wall_h`, `wall_v`).
`finalize` writes the `~/.cache/udt/wpaper` symlink, then calls
`udt-accent "$HOME/.cache/udt/wpaper"`. That call is never fatal: if the binary
is missing or exits non-zero, the wallpaper still stands. `udt-accent` owns the
whole palette (rofi, Hyprland, Firefox, quickshell, Sublime), so nothing here
renders colours first.
## External integration (outside this repo)
- `~/bin/udt-accent` — unified desktop theme accent picker; reads
`~/.cache/udt/wpaper`, writes the rest of the palette.
- `~/.config/hypr/sections/autostart.lua` → `wallp --restore`.
- `~/.config/hypr/sections/keybindings.lua` → `wallp --set` (mainMod+Return).
- Old `~/bin/multiwal.sh` + `qar-lastwall.sh` kept as fallback, unreferenced.
## Commits
Pre-commit gitleaks hook prints ASCII art — normal; the commit succeeds when it
reports "no leaks found".
|
