docs: home-manager module implementation plan
This commit is contained in:
elwrcl committed
1 parent
381eb72721
commit
b294210a8f
1 file changed
+250
@@ -0,0 +1,250 @@
|
||||
# valw home-manager module 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:** `flake.homeModules.default` with `programs.valw.{enable, package, settings}`, the config checked at build time by `valw __check-config`, plus a README.
|
||||
|
||||
**Architecture:** A strict `config::check` behind a hidden CLI command; a dendritic `nix/home-module.ulu.nix` that writes `settings` with `pkgs.formats.toml` through a checking `runCommand`; two flake checks that evaluate the module with stub home-manager options (no new input).
|
||||
|
||||
**Tech Stack:** Rust 2024; Nix (flake-parts, dendritic `*.ulu.nix`), `pkgs.formats.toml`, `pkgs.testers.testBuildFailure`.
|
||||
|
||||
**Spec:** `docs/superpowers/specs/2026-10-03-valw-home-manager-design.md`
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- jj only; `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check`, `cargo nextest run`, `nix flake check`.
|
||||
- No manual `imports = [ ... ]` in the dendritic flake; no new flake inputs.
|
||||
- Error text for unknown keys: `unknown config key: a` / `unknown config keys: a, b`.
|
||||
|
||||
## Review Focus
|
||||
|
||||
1. **The checked config is byte-identical to what valw reads** (no re-serialisation in between). Task 2's check greps the installed file.
|
||||
2. **`__check-config` in the sandbox** (no HOME, no Wayland, no niri) must work. Task 2's checks run it there.
|
||||
3. **Empty `settings` writes no file** (valw defaults apply). Task 2 asserts it.
|
||||
4. **A typo'd key fails the build with the key's name.** Task 2's rejects check.
|
||||
5. **Toolbar state stays writable.** Not managed (spec), README says so.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: `valw __check-config`
|
||||
|
||||
**Files:** `src/config.rs`, `src/main.rs`.
|
||||
|
||||
- [ ] **Step 1: Failing tests**
|
||||
|
||||
`config.rs` tests:
|
||||
|
||||
```rust
|
||||
#[test]
|
||||
fn check_accepts_valid_files() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let path = dir.path().join("config.toml");
|
||||
std::fs::write(&path, "[preview]\ntimeout_secs = 3\n[sound]\nvolume = 0.4\n").unwrap();
|
||||
check(&path).unwrap();
|
||||
std::fs::write(&path, "").unwrap();
|
||||
check(&path).unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn check_rejects_invalid_values_with_valws_message() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let path = dir.path().join("config.toml");
|
||||
std::fs::write(&path, "[sound]\nvolume = 2.0\n").unwrap();
|
||||
let err = format!("{:#}", check(&path).unwrap_err());
|
||||
assert!(err.contains("sound.volume must be between 0 and 1"), "{err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn check_rejects_unknown_keys_by_name() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let path = dir.path().join("config.toml");
|
||||
std::fs::write(&path, "[preview]\ntimout_secs = 3\n").unwrap();
|
||||
assert_eq!(check(&path).unwrap_err().to_string(), "unknown config key: preview.timout_secs");
|
||||
std::fs::write(&path, "[preview]\ntimout_secs = 3\n[sund]\nx = 1\n").unwrap();
|
||||
assert_eq!(
|
||||
check(&path).unwrap_err().to_string(),
|
||||
"unknown config keys: preview.timout_secs, sund"
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
`main.rs`: `flag_conflicts` gains `assert!(parses(&["__check-config", "c.toml"]));` and `assert!(!parses(&["__check-config"]));`; the help test gains `assert!(!help.contains("check-config"), "{help}");`.
|
||||
|
||||
- [ ] **Step 2: Implement**
|
||||
|
||||
`config.rs`:
|
||||
|
||||
```rust
|
||||
/// Checks a config file strictly, for home-manager's build: invalid values
|
||||
/// and unknown keys are errors (at run time unknown keys only warn).
|
||||
pub fn check(path: &Path) -> Result<()> {
|
||||
let text = std::fs::read_to_string(path).with_context(|| format!("could not read {}", path.display()))?;
|
||||
let (_, unknown) = parse(&text).with_context(|| format!("invalid config file {}", path.display()))?;
|
||||
match unknown.len() {
|
||||
0 => Ok(()),
|
||||
1 => bail!("unknown config key: {}", unknown[0]),
|
||||
_ => bail!("unknown config keys: {}", unknown.join(", ")),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`main.rs`: `/// Internal: check a config file (home-manager runs it at build time).` `#[command(name = "__check-config", hide = true)] CheckConfig { file: PathBuf }` → `Command::CheckConfig { file } => config::check(&file),`.
|
||||
|
||||
- [ ] **Step 3: Run** (+3 tests), clippy, fmt. **Step 4: Commit** `feat: valw __check-config`.
|
||||
|
||||
---
|
||||
|
||||
### Task 2: The module and its checks
|
||||
|
||||
**Files:** create `nix/home-module.ulu.nix`; modify `nix/checks.ulu.nix`.
|
||||
|
||||
- [ ] **Step 1: Failing checks** — `nix/checks.ulu.nix`: take `self` and `lib` in the module arguments, and add
|
||||
|
||||
```nix
|
||||
# The home-manager module, evaluated with stand-ins for the two
|
||||
# home-manager options it sets (no home-manager input needed).
|
||||
homeModule =
|
||||
settings:
|
||||
(lib.evalModules {
|
||||
modules = [
|
||||
self.homeModules.default
|
||||
(
|
||||
{ lib, ... }:
|
||||
{
|
||||
options.home.packages = lib.mkOption {
|
||||
type = lib.types.listOf lib.types.package;
|
||||
default = [ ];
|
||||
};
|
||||
options.xdg.configFile = lib.mkOption {
|
||||
type = lib.types.attrsOf (
|
||||
lib.types.submodule { options.source = lib.mkOption { type = lib.types.path; }; }
|
||||
);
|
||||
default = { };
|
||||
};
|
||||
config._module.args.pkgs = pkgs;
|
||||
config.programs.valw = {
|
||||
enable = true;
|
||||
inherit settings;
|
||||
};
|
||||
}
|
||||
)
|
||||
];
|
||||
}).config;
|
||||
```
|
||||
|
||||
(in the `let`), and in `checks`:
|
||||
|
||||
```nix
|
||||
home-module =
|
||||
let
|
||||
plain = homeModule { };
|
||||
set = homeModule {
|
||||
preview.timeout_secs = 3;
|
||||
sound.volume = 0.4;
|
||||
};
|
||||
in
|
||||
assert lib.assertMsg (plain.home.packages == [ valw ]) "the module installs valw";
|
||||
assert lib.assertMsg (plain.xdg.configFile == { }) "no settings, no config file";
|
||||
pkgs.runCommand "valw-home-module" { } ''
|
||||
grep -qx 'timeout_secs = 3' ${set.xdg.configFile."valw/config.toml".source}
|
||||
grep -qx 'volume = 0.4' ${set.xdg.configFile."valw/config.toml".source}
|
||||
touch $out
|
||||
'';
|
||||
|
||||
home-module-rejects =
|
||||
let
|
||||
fails = settings: pkgs.testers.testBuildFailure (homeModule settings).xdg.configFile."valw/config.toml".source;
|
||||
in
|
||||
pkgs.runCommand "valw-home-module-rejects" { } ''
|
||||
grep -q 'sound.volume must be between 0 and 1' ${fails { sound.volume = 2; }}/testBuildFailure.log
|
||||
grep -q 'unknown config key: preview.timout_secs' ${fails { preview.timout_secs = 3; }}/testBuildFailure.log
|
||||
touch $out
|
||||
'';
|
||||
```
|
||||
|
||||
Run `nix flake check path:. --no-build` (evaluation only) → fails: `self.homeModules` missing.
|
||||
|
||||
- [ ] **Step 2: The module** — `nix/home-module.ulu.nix`:
|
||||
|
||||
```nix
|
||||
{ withSystem, ... }:
|
||||
{
|
||||
flake.homeModules.default =
|
||||
{
|
||||
config,
|
||||
lib,
|
||||
pkgs,
|
||||
...
|
||||
}:
|
||||
let
|
||||
cfg = config.programs.valw;
|
||||
toml = pkgs.formats.toml { };
|
||||
# valw checks its own config: a typo or a bad value fails the build.
|
||||
checked =
|
||||
settings:
|
||||
let
|
||||
file = toml.generate "valw-config.toml" settings;
|
||||
in
|
||||
pkgs.runCommand "valw-config.toml" { } ''
|
||||
${lib.getExe cfg.package} __check-config ${file}
|
||||
cp ${file} $out
|
||||
'';
|
||||
in
|
||||
{
|
||||
options.programs.valw = {
|
||||
enable = lib.mkEnableOption "valw, macOS-style screenshots for niri";
|
||||
package = lib.mkOption {
|
||||
type = lib.types.package;
|
||||
default = withSystem pkgs.stdenv.hostPlatform.system ({ config, ... }: config.packages.default);
|
||||
defaultText = lib.literalExpression "valw.packages.\${system}.default";
|
||||
description = "The valw package to install and to check the settings with.";
|
||||
};
|
||||
settings = lib.mkOption {
|
||||
inherit (toml) type;
|
||||
default = { };
|
||||
example = lib.literalExpression ''
|
||||
{
|
||||
preview.timeout_secs = 3;
|
||||
sound.volume = 0.4;
|
||||
capture.window_shadow = true;
|
||||
}
|
||||
'';
|
||||
description = ''
|
||||
valw's config (`$XDG_CONFIG_HOME/valw/config.toml`), checked by
|
||||
valw at build time. Empty means valw's defaults.
|
||||
'';
|
||||
};
|
||||
};
|
||||
|
||||
config = lib.mkIf cfg.enable {
|
||||
home.packages = [ cfg.package ];
|
||||
xdg.configFile."valw/config.toml" = lib.mkIf (cfg.settings != { }) {
|
||||
source = checked cfg.settings;
|
||||
};
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run** — `nix flake check path:. -L --keep-going`: all pass, including `home-module` and `home-module-rejects`.
|
||||
|
||||
- [ ] **Step 4: Commit** `feat: home-manager module`.
|
||||
|
||||
---
|
||||
|
||||
### Task 3: README and checklist
|
||||
|
||||
- [ ] `README.md`: what valw is (one paragraph); install (`nix run`, flake package, the module); the module example (from the spec) and a note that the toolbar's memory stays in `~/.local/state/valw`; niri bind examples (`Print` → `valw screen`, `Mod+Shift+S` → `valw region`, plus `window`, `zoom`, `toolbar`); a table of the commands; `valw doctor`; where logs are.
|
||||
- [ ] Checklist section:
|
||||
|
||||
```markdown
|
||||
|
||||
## home-manager module
|
||||
|
||||
- [ ] copland: `home-valw.ulu.nix` uses `inputs.valw.homeModules.default` with `programs.valw.enable = true` and a few `settings`; rebuild; `~/.config/valw/config.toml` is the store file with those settings.
|
||||
- [ ] A typo in `settings` (e.g. `preview.timout_secs`) fails the rebuild naming the key.
|
||||
- [ ] The toolbar still remembers its options (state file stays writable).
|
||||
- [ ] New binds for `valw window`, `valw zoom`, `valw toolbar` in copland's niri keybinds.
|
||||
```
|
||||
|
||||
- [ ] Commit `docs: README and home-manager checklist`.
|
||||
Reference in new issue
Block a user