9 Commits

Author SHA1 Message Date
finn.markwitz e6bd69d880 config: Disable Dank 2026-07-27 09:15:07 +02:00
finn.markwitz 87e5204d85 docs(plan): pin home-manager to release-26.05 and drop redundant niri keybinds
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 14:10:45 +02:00
finn.markwitz 6c95ed3ebb feat(dank): enable DMS/niri session on mibook, pin HM to release-26.05, drop redundant keybinds
- Pin home-manager input to release-26.05 to match nixpkgs (was resolving
  to HM master / 26.11, causing a Home Manager version mismatch warning).
- Drop niri.enableKeybinds = true from the dank HM config; keybinds are
  already provided by the imported DMS niri homeModule (includes), and using
  both together triggered the "enableKeybinds and includes.enable" warning.
- Enable my.profiles.dank on mibook (machines/mibook/environments.nix).
- Rebuild confirmed exit 0 with both target warnings resolved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 14:09:59 +02:00
finn.markwitz 2520010340 feat(dank): add DankMaterialShell (niri) profile
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 13:20:14 +02:00
finn.markwitz 87b14accac docs(plan): use self.inputs in top-level imports to avoid module recursion
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 13:17:11 +02:00
finn.markwitz 4d42d58126 feat(home-manager): add opt-in my.profiles.home-manager module
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 13:15:54 +02:00
finn.markwitz 06bc35f26d chore: add home-manager, niri-flake, and DankMaterialShell flake inputs
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 12:22:08 +02:00
finn.markwitz 826a612d9d docs: implementation plan for DankMaterialShell (niri) profile
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 12:19:05 +02:00
finn.markwitz d3a3b12e37 docs: design for DankMaterialShell (niri) profile
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN
2026-07-24 12:13:49 +02:00
16 changed files with 827 additions and 730 deletions
@@ -0,0 +1,289 @@
# DankMaterialShell (niri) Profile 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:** Add a `my.profiles.dank` NixOS profile that runs DankMaterialShell (DMS) on the niri Wayland compositor as a login session parallel to KDE on mibook, backed by a new opt-in `my.profiles.home-manager` module.
**Architecture:** Three flake inputs (`home-manager`, `niri` = niri-flake, `dank` = DankMaterialShell) are added to `flake.nix`. A `my.profiles.home-manager` module unconditionally imports the home-manager NixOS module and, when enabled, sets global HM settings. A `my.profiles.dank` module enables `my.profiles.home-manager` as a dependency, turns on niri (system session) + the DMS nixosModule (daemons/packages), and configures `home-manager.users.finn` with the DMS + niri-flake HM modules for keybinds/spawn. mibook enables `dank`.
**Tech Stack:** Nix flakes, flake-parts, NixOS modules, home-manager (as NixOS module), niri-flake, DankMaterialShell flake, quickshell (from `pkgs.unstable`).
## Global Constraints
- Do **not** modify `machines/configuration.nix`. `inputs` and `self` are already threaded into every module via `_module.args`; consume them as module arguments.
- **Top-level `imports` must reference flake modules via `self.inputs.*`, not `inputs.*`.** `self` is a specialArg (available during `imports` resolution); `inputs` comes from `_module.args` (config-derived) and using it in an `imports` list causes infinite recursion. Inside the `config` body (including nested `home-manager.users.<name>.imports`), either `inputs` or `self.inputs` is fine.
- Base channel is pinned `nixpkgs/nixos-26.05`; `pkgs.unstable` overlay is available everywhere. quickshell must come from `pkgs.unstable.quickshell` (needs ≥ 0.3.0).
- home-manager scoped to user `finn` only; `home.stateVersion = "26.05"`.
- Follow the existing profile pattern exactly: `let cfg = config.my.profiles.<name>; in { options.my.profiles.<name>.enable = lib.mkEnableOption "..."; config = lib.mkIf cfg.enable { ... }; }`.
- Format every new/edited `.nix` file with `nixfmt-rfc-style` before committing.
- Commit messages end with the repo's trailer lines (Co-Authored-By + Claude-Session) as seen in recent history.
- KDE (`my.profiles.kde-desktop`) stays enabled on mibook; do not remove it.
---
### Task 1: Add flake inputs
**Files:**
- Modify: `flake.nix:4-15` (the `inputs = { ... }` block)
**Interfaces:**
- Produces: flake inputs `inputs.home-manager`, `inputs.niri`, `inputs.dank`, reachable from any NixOS module (via the existing `_module.args.inputs = self.inputs`). Later tasks consume `inputs.home-manager.nixosModules.home-manager`, `inputs.niri.homeModules.niri`, `inputs.dank.nixosModules.dank-material-shell`, `inputs.dank.homeModules.dank-material-shell`, `inputs.dank.homeModules.niri`.
- [ ] **Step 1: Add the three inputs**
In `flake.nix`, inside the `inputs = { ... }` block, after the `nixos-generators` entry and before the closing `};`, add:
```nix
home-manager = {
url = "github:nix-community/home-manager/release-26.05";
inputs.nixpkgs.follows = "nixpkgs";
};
niri.url = "github:sodiboo/niri-flake";
dank.url = "github:AvengeMedia/DankMaterialShell";
```
- [ ] **Step 2: Resolve the lock file**
Run: `nix flake lock`
Expected: completes without error; `flake.lock` gains `home-manager`, `niri`, `niri-flake`-transitive, and `dank` (DankMaterialShell) nodes. If it reports a bad URL, re-check the `github:owner/repo` strings.
- [ ] **Step 3: Verify inputs expose the expected outputs**
Run: `nix eval --raw '.#nixosConfigurations.mibook.pkgs.system'` first to confirm the flake still evaluates (expected: `x86_64-linux`).
Then run: `nix flake show 'github:AvengeMedia/DankMaterialShell' --allow-import-from-derivation 2>/dev/null | grep -E 'dank-material-shell|nixosModules|homeModules'`
Expected: output lists `nixosModules.dank-material-shell` and `homeModules.dank-material-shell` and `homeModules.niri`. If the niri output name differs (e.g. `dankMaterialShell.niri`), note the actual name — Task 3 Step 1 must use whatever this shows.
- [ ] **Step 4: Format and commit**
```bash
nixfmt-rfc-style flake.nix
git add flake.nix flake.lock
git commit -m "chore: add home-manager, niri-flake, and DankMaterialShell flake inputs
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN"
```
---
### Task 2: `my.profiles.home-manager` module
**Files:**
- Create: `modules/environments/home-manager/default.nix`
- Modify: `modules/environments/default.nix` (add `./home-manager` to `imports`)
**Interfaces:**
- Consumes: `inputs.home-manager.nixosModules.home-manager` (Task 1).
- Produces: option `my.profiles.home-manager.enable`. When enabled, sets `home-manager.useGlobalPkgs = true`, `home-manager.useUserPackages = true`, `home-manager.extraSpecialArgs = { inherit inputs self; }`. Also makes the `home-manager.users.<name>` option available (from the unconditional import) so Task 3 can populate `home-manager.users.finn`.
- [ ] **Step 1: Create the module**
Create `modules/environments/home-manager/default.nix`:
```nix
{
config,
lib,
inputs,
self,
...
}:
let
cfg = config.my.profiles.home-manager;
in
{
imports = [ self.inputs.home-manager.nixosModules.home-manager ];
options.my.profiles.home-manager.enable =
lib.mkEnableOption "home-manager integration";
config = lib.mkIf cfg.enable {
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
home-manager.extraSpecialArgs = { inherit inputs self; };
};
}
```
- [ ] **Step 2: Register the module**
In `modules/environments/default.nix`, add `./home-manager` to the `imports` list (place it after `./hyprland`):
```nix
./hyprland
./home-manager
```
- [ ] **Step 3: Verify it evaluates disabled (no behavior change)**
Run: `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel' --dry-run`
Expected: evaluates and shows a build plan with no errors. Because `my.profiles.home-manager.enable` defaults to false, importing the HM module must not change the build outcome.
- [ ] **Step 4: Verify the option exists and defaults false**
Run: `nix eval '.#nixosConfigurations.mibook.config.my.profiles.home-manager.enable'`
Expected: `false`
- [ ] **Step 5: Format and commit**
```bash
nixfmt-rfc-style modules/environments/home-manager/default.nix modules/environments/default.nix
git add modules/environments/home-manager/default.nix modules/environments/default.nix
git commit -m "feat(home-manager): add opt-in my.profiles.home-manager module
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN"
```
---
### Task 3: `my.profiles.dank` module
**Files:**
- Create: `modules/environments/dank/default.nix`
- Modify: `modules/environments/default.nix` (add `./dank` to `imports`)
**Interfaces:**
- Consumes: `my.profiles.home-manager.enable` (Task 2); `inputs.dank.nixosModules.dank-material-shell`, `inputs.dank.homeModules.dank-material-shell`, `inputs.dank.homeModules.niri`, `inputs.niri.homeModules.niri` (Task 1); `pkgs.unstable.quickshell`.
- Produces: option `my.profiles.dank.enable`.
- [ ] **Step 1: Create the module**
Create `modules/environments/dank/default.nix`. Use the exact `homeModules`/`nixosModules` output names confirmed in Task 1 Step 3 — the block below assumes `dank-material-shell` and `niri`:
```nix
{
config,
lib,
pkgs,
inputs,
self,
...
}:
let
cfg = config.my.profiles.dank;
in
{
imports = [ self.inputs.dank.nixosModules.dank-material-shell ];
options.my.profiles.dank.enable = lib.mkEnableOption "DankMaterialShell on niri";
config = lib.mkIf cfg.enable {
# Dependency: declarative user config comes from home-manager.
my.profiles.home-manager.enable = true;
# System side: niri Wayland session + DMS daemons/packages.
programs.niri.enable = true;
programs.dank-material-shell = {
enable = true;
systemd.enable = true;
quickshell.package = pkgs.unstable.quickshell;
};
# Home side: DMS shell + niri spawn for finn (keybinds come via includes).
home-manager.users.finn = {
imports = [
inputs.niri.homeModules.niri
inputs.dank.homeModules.dank-material-shell
inputs.dank.homeModules.niri
];
programs.dank-material-shell = {
enable = true;
systemd.enable = true;
quickshell.package = pkgs.unstable.quickshell;
# niri.enableKeybinds intentionally omitted: DMS's niri `includes.enable`
# (default true) already brings in the generated binds.kdl plus theming;
# setting enableKeybinds too triggers an upstream "not recommended" warning.
niri.enableSpawn = true;
};
home.stateVersion = "26.05";
};
};
}
```
- [ ] **Step 2: Register the module**
In `modules/environments/default.nix`, add `./dank` to the `imports` list (after `./home-manager`):
```nix
./home-manager
./dank
```
- [ ] **Step 3: Verify it evaluates disabled**
Run: `nix eval '.#nixosConfigurations.mibook.config.my.profiles.dank.enable'`
Expected: `false`
Run: `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel' --dry-run`
Expected: evaluates without error (dank disabled → no behavior change yet).
- [ ] **Step 4: Format and commit**
```bash
nixfmt-rfc-style modules/environments/dank/default.nix modules/environments/default.nix
git add modules/environments/dank/default.nix modules/environments/default.nix
git commit -m "feat(dank): add DankMaterialShell (niri) profile
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN"
```
---
### Task 4: Enable on mibook and build the full toplevel
**Files:**
- Modify: `machines/mibook/environments.nix:7-17` (the `my.profiles = { ... }` block)
**Interfaces:**
- Consumes: `my.profiles.dank.enable` (Task 3).
- [ ] **Step 1: Enable the profile**
In `machines/mibook/environments.nix`, inside the `my.profiles = { ... }` block, add:
```nix
dank.enable = true;
```
- [ ] **Step 2: Build the full toplevel (the real test)**
Run: `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
Expected: builds successfully. This exercises the DMS package, quickshell from unstable, niri, and the home-manager generation for finn.
If it fails on a **quickshell/Qt6 version mismatch** (see spec risks): drop `quickshell.package = pkgs.unstable.quickshell;` from **both** the system and HM `programs.dank-material-shell` blocks in `modules/environments/dank/default.nix` and rebuild, letting DMS's module pick its own default quickshell. If it fails on an **unknown HM option** (e.g. `niri.enableKeybinds`), run `nix eval '.#nixosConfigurations.mibook.config.home-manager.users.finn.programs.dank-material-shell' --apply builtins.attrNames 2>&1 | head` to list the real option names and adjust. Re-run the build until it passes.
- [ ] **Step 3: Run flake check**
Run: `nix flake check`
Expected: passes (all nixosConfigurations evaluate). If `nix flake check` is slow or pulls DMS's own checks, `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'` from Step 2 passing is the authoritative gate.
- [ ] **Step 4: Format and commit**
```bash
nixfmt-rfc-style machines/mibook/environments.nix
git add machines/mibook/environments.nix modules/environments/dank/default.nix
git commit -m "feat(mibook): enable DankMaterialShell (niri) session
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018Sv2QAunLcLo3tS1YsfLgN"
```
- [ ] **Step 5: Manual acceptance (human, on hardware)**
Run: `sudo nixos-rebuild test --flake '.#mibook'`
Then log out, pick the **niri** session at SDDM, log in as finn.
Expected: DMS bar/shell appears; `Mod+Space` opens the launcher; `Mod+V` opens the clipboard; the KDE session is still selectable and works. Note this step cannot be automated — it requires the physical machine.
---
## Notes for the implementer
- **Order matters:** Task 1 must land first (inputs must resolve before any module can import them). Tasks 2→3→4 are strictly sequential.
- **Output-name drift is the top risk.** The DMS flake has renamed outputs over time (there are deprecated aliases like `dankMaterialShell.niri`). Task 1 Step 3 pins down the real names against the locked revision; use those, not the names in this plan, if they differ.
- **No unit-test framework here.** Nix evaluation + a successful `toplevel` build *is* the test. Do not fabricate a test harness.
- Do not touch `machines/configuration.nix`, `machines/jupiter/*`, or the KDE profile.
@@ -1,154 +0,0 @@
# Jellyfin Hardware Transcoding (jupiter) 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:** Give jupiter's Jellyfin service access to the Intel iGPU's VAAPI render node so Quick Sync hardware transcoding can be enabled, instead of every transcode falling back to CPU.
**Architecture:** One NixOS module change (`modules/environments/jellyfin/default.nix`) grants the `jellyfin` systemd service supplementary access to the `video`/`render` groups and installs `libva-utils` for verification. This is declarative and build-verifiable from the Mac. Enabling Quick Sync inside Jellyfin's own dashboard, and the on-machine verification, is a manual step run by the user on jupiter after deploy — the NixOS module has no option for it and this environment's convention is that the assistant never SSHes into jupiter directly (see `docs/superpowers/specs/2026-07-26-jellyfin-hw-transcoding.md`).
**Tech Stack:** NixOS (flake-parts), nixpkgs `services.jellyfin` module, VAAPI/`intel-media-driver`, `libva-utils`.
## Global Constraints
- No SSH from the assistant into jupiter — all on-machine commands are given to the user to run and paste back.
- Follow the existing profile pattern in `modules/environments/jellyfin/default.nix` (`config = lib.mkIf cfg.enable { ... }`); don't introduce a new toggle option — hardcode the hardware-acceleration wiring on, per the approved spec.
- Verify locally via `nix eval` / `nix build` before asking the user to deploy.
---
### Task 1: Grant Jellyfin access to the iGPU and verify the build
**Files:**
- Modify: `modules/environments/jellyfin/default.nix`
**Interfaces:**
- Produces: `systemd.services.jellyfin.serviceConfig.SupplementaryGroups = [ "video" "render" ];` — verified via `nix eval` in Step 2.
- [ ] **Step 1: Add the device-access config and `libva-utils` package**
Read the current file first (`modules/environments/jellyfin/default.nix`), then edit the `config = lib.mkIf cfg.enable { ... }` block so it reads:
```nix
config = lib.mkIf cfg.enable {
services.jellyfin = {
enable = true;
openFirewall = true;
};
environment.systemPackages = [ pkgs.libva-utils ];
my.homepage.services = [
{
group = "Media";
name = "Jellyfin";
description = "Media server";
href = "http://${hostName}:${toString port}";
icon = "jellyfin.png";
}
];
systemd.services.jellyfin = {
after = [ "network-online.target" ];
serviceConfig.SupplementaryGroups = [
"video"
"render"
];
};
};
```
Note the two existing `systemd.services.jellyfin` keys (`after`) and the new `serviceConfig.SupplementaryGroups` now live in the same attrset — don't create a second `systemd.services.jellyfin = { ... }` block, it would overwrite the first.
- [ ] **Step 2: Verify the rendered config with `nix eval`**
Run (from the repo root on the Mac):
```bash
nix eval '.#nixosConfigurations.jupiter.config.systemd.services.jellyfin.serviceConfig.SupplementaryGroups' \
--extra-experimental-features 'nix-command flakes'
```
Expected output: `[ "video" "render" ]`
- [ ] **Step 3: Verify the machine still builds**
Run:
```bash
nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel' \
--extra-experimental-features 'nix-command flakes' --no-link
```
Expected: build succeeds with no errors (may take a while; watch for any evaluation error mentioning `jellyfin` or `libva-utils`).
- [ ] **Step 4: Format and commit**
```bash
nixfmt-rfc-style modules/environments/jellyfin/default.nix
git add modules/environments/jellyfin/default.nix
git commit -m "feat(jellyfin): grant iGPU access for Quick Sync hardware transcoding"
```
---
### Task 2: Deploy on jupiter and enable Quick Sync (user-executed)
**Files:** none (on-machine deploy + Jellyfin dashboard UI)
**Interfaces:**
- Consumes: the `SupplementaryGroups` change from Task 1, already merged into the flake.
These steps run **on jupiter**, by the user — paste the output back so we can confirm each one before moving to the next.
- [ ] **Step 1: Deploy**
```bash
sudo nixos-rebuild switch --flake '.#jupiter'
```
Expected: switch succeeds, no errors mentioning `jellyfin`.
- [ ] **Step 2: Confirm the service picked up the new groups**
```bash
systemctl show jellyfin -p SupplementaryGroups
systemctl status jellyfin --no-pager
```
Expected: `SupplementaryGroups=video render` (order may vary) and the service is `active (running)`.
- [ ] **Step 3: Confirm VAAPI driver loads**
```bash
vainfo
```
Expected: output starts with something like `vainfo: VA-API version: 1.x` and `Driver version: Intel iHD driver`, followed by a list of supported VAProfiles/VAEntrypoints (e.g. `VAProfileH264Main : VAEntrypointVLD`, `VAEntrypointEncSlice`).
If this instead prints a permissions or "no VA display" error, paste it back — that means the group grant isn't reaching the process and Task 1 needs a follow-up fix (e.g. the jellyfin service may be more sandboxed than expected, requiring an explicit `DeviceAllow=char-drm rw` in `serviceConfig` as well).
- [ ] **Step 4: Enable Quick Sync in the Jellyfin dashboard**
In the Jellyfin web UI:
1. **Dashboard → Playback**.
2. Hardware acceleration: **Intel QuickSync (QSV)**.
3. VA-API device: `/dev/dri/renderD128`.
4. Enable hardware decoding for the codecs your library uses (H264 at minimum).
5. If the library has HDR content, enable tone-mapping.
6. Save.
- [ ] **Step 5: Functional check**
Play a file that requires transcoding (or force a lower quality in the client's playback settings to trigger one), then:
```bash
journalctl -u jellyfin -n 50 --no-pager
```
Look for a line referencing `qsv` or `vaapi` in the transcode command. Separately, watch CPU usage (`htop`) during playback — it should stay low on the core doing the transcode, rather than pegging at 100%, since the iGPU is now doing the encode/decode work.
## Self-Review Notes
- Spec coverage: NixOS change (Task 1) ✓, manual dashboard step (Task 2 Step 4) ✓, verification via `vainfo`/build (Task 1 Step 2-3, Task 2 Step 3) ✓, functional check (Task 2 Step 5) ✓. Toggle option explicitly excluded per approved spec — not present, correctly.
- No placeholders — every step has literal commands/code.
- `SupplementaryGroups` key/value matches exactly between Task 1 (produced) and Task 2 (consumed/checked).
@@ -1,189 +0,0 @@
# Alexa Media Player Integration — 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:** Package the `alexa_media_player` HACS component declaratively on jupiter's Home Assistant so HA can drive the household Echo devices (TTS/announce, media, sensors).
**Architecture:** Add one `buildHomeAssistantComponent` entry to `services.home-assistant.customComponents` (same pattern as the existing `ha-sourdough`). The component has real Python deps, so the module's `let` block also defines two supporting derivations built against HA's own interpreter: a new `dictor` package and an `alexapy` version bump. No HACS runtime, no YAML config — the integration is added through the HA UI after the rebuild.
**Tech Stack:** NixOS, `pkgs.buildHomeAssistantComponent`, `buildPythonPackage`, `fetchFromGitHub`/`fetchFromGitLab`/`fetchPypi`.
## Global Constraints
- Target machine: **jupiter** only. All edits live in `modules/environments/home-assistant/default.nix`.
- Python dep derivations MUST build against Home Assistant's interpreter set — `pkgs.home-assistant.python3Packages` — the same set `buildHomeAssistantComponent` uses. Do not use top-level `pkgs.python3Packages`.
- Manifest requirements are enforced at build time by `manifestCheckPhase` and again by HA at runtime. Every requirement must resolve to an installed dist satisfying its specifier. Exact pins (verbatim from `alexa_media_player` v5.15.7 `manifest.json`):
- `alexapy==1.29.25`
- `dictor>=0.1.12,<0.2`
- `wrapt>=1.14.0` (nixpkgs 1.17.2 — already satisfied)
- `packaging>=20.3` (nixpkgs 26.1 — already satisfied)
- Pinned artifacts (all three hashes verified to build during planning):
| Artifact | Fetcher | Ref / version | Hash |
| ------------------ | ---------------- | ------------- | ------------------------------------------------- |
| alexa_media_player | fetchFromGitHub | `v5.15.7` | `sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=` |
| alexapy | fetchFromGitLab | `v1.29.25` | `sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4=` |
| dictor | fetchPypi (sdist)| `0.1.12` | `sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs=` |
---
## File Structure
Single file touched: `modules/environments/home-assistant/default.nix`.
- Its `let` block gains `haPython`, `dictor`, and `alexapy` bindings.
- Its `services.home-assistant.customComponents` list gains a second entry (`alexa_media`) alongside the existing `sourdough` entry.
No new files. The two supporting derivations are small and specific to this component, so they live inline in the module's `let` block next to their only consumer (files that change together live together).
---
### Task 1: Package `alexa_media_player` with its Python dependencies
**Files:**
- Modify: `modules/environments/home-assistant/default.nix` (the `let` block, currently lines 9-12; and the `customComponents` list, currently lines 29-41)
**Interfaces:**
- Consumes: `pkgs.home-assistant.python3Packages` (HA interpreter set), `pkgs.buildHomeAssistantComponent`, `pkgs.fetchFromGitHub`, `pkgs.fetchFromGitLab`.
- Produces: a second `customComponents` entry with `domain = "alexa_media"`. No other module consumes these `let` bindings.
- [ ] **Step 1: Add the supporting derivations to the `let` block**
Edit the `let` block so it reads exactly:
```nix
let
cfg = config.my.profiles.home-assistant;
hostName = config.networking.hostName;
# Python deps for the alexa_media_player custom component (Task: Alexa).
# Built against Home Assistant's own interpreter — the same set
# buildHomeAssistantComponent uses — so HA's build-time and runtime
# manifest-requirement checks are satisfied.
haPython = pkgs.home-assistant.python3Packages;
# dictor is not in nixpkgs; alexa_media_player needs dictor>=0.1.12,<0.2.
# Pure-Python, no runtime deps, legacy setup.py.
dictor = haPython.buildPythonPackage {
pname = "dictor";
version = "0.1.12";
format = "setuptools";
src = haPython.fetchPypi {
pname = "dictor";
version = "0.1.12";
hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs=";
};
build-system = [ haPython.setuptools ];
doCheck = false;
pythonImportsCheck = [ "dictor" ];
};
# nixpkgs ships alexapy 1.29.22; the manifest pins ==1.29.25. Patch bump.
# nixpkgs fetches alexapy from GitLab (keatontaylor/alexapy), tag v<version>.
alexapy = haPython.alexapy.overridePythonAttrs (old: {
version = "1.29.25";
src = pkgs.fetchFromGitLab {
owner = "keatontaylor";
repo = "alexapy";
tag = "v1.29.25";
hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4=";
};
});
in
```
- [ ] **Step 2: Add the `alexa_media` entry to `customComponents`**
In `services.home-assistant.customComponents`, immediately after the closing `)` of the existing `sourdough` entry (current line 40) and before the list's closing `]` (current line 41), add:
```nix
(pkgs.buildHomeAssistantComponent {
owner = "Alandtse";
domain = "alexa_media";
version = "5.15.7";
src = pkgs.fetchFromGitHub {
owner = "Alandtse";
repo = "alexa_media_player";
rev = "v5.15.7";
hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=";
};
# Every manifest requirement must be importable at a satisfying
# version or manifestCheckPhase fails the build.
dependencies = [
alexapy
dictor
haPython.wrapt
haPython.packaging
];
})
```
- [ ] **Step 3: Format the file**
Run: `nixfmt-rfc-style modules/environments/home-assistant/default.nix`
Expected: exits 0, no diff surprises (re-read the file if unsure).
- [ ] **Step 4: Build the component in isolation first (fast feedback)**
This is the real test: it runs `manifestCheckPhase`, which fails loudly if any of the four requirements is unmet. It was verified to succeed during planning.
Run:
```bash
nix build --impure --no-link --print-out-paths --expr '
let
pkgs = (builtins.getFlake (toString ./.)).nixosConfigurations.jupiter.pkgs;
py = pkgs.home-assistant.python3Packages;
dictor = py.buildPythonPackage {
pname = "dictor"; version = "0.1.12"; format = "setuptools";
src = py.fetchPypi { pname = "dictor"; version = "0.1.12"; hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs="; };
build-system = [ py.setuptools ]; doCheck = false; pythonImportsCheck = [ "dictor" ];
};
alexapy = py.alexapy.overridePythonAttrs (old: {
version = "1.29.25";
src = pkgs.fetchFromGitLab { owner = "keatontaylor"; repo = "alexapy"; tag = "v1.29.25"; hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4="; };
});
in pkgs.buildHomeAssistantComponent {
owner = "Alandtse"; domain = "alexa_media"; version = "5.15.7";
src = pkgs.fetchFromGitHub { owner = "Alandtse"; repo = "alexa_media_player"; rev = "v5.15.7"; hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI="; };
dependencies = [ alexapy dictor py.wrapt py.packaging ];
}'
```
Expected: prints a `/nix/store/...-Alandtse-alexa_media-5.15.7` path, exit 0. If it fails with `<pkg><specifier> not satisfied by version ...`, a dependency version drifted — re-check the manifest pin against the provided dep.
- [ ] **Step 5: Build the whole jupiter system (integration gate)**
Run: `nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel'`
Expected: builds to completion, exit 0. This confirms the module edits evaluate and the component is wired into HA's package.
- [ ] **Step 6: Commit**
```bash
git add modules/environments/home-assistant/default.nix
git commit -m "$(cat <<'EOF'
feat(home-assistant): add alexa_media_player custom component
Package the Alexa Media Player HACS component declaratively (v5.15.7),
so HA can drive the Echo devices (TTS/announce, media, sensors). Needs
dictor 0.1.12 (absent from nixpkgs) and an alexapy 1.29.22 -> 1.29.25
bump to satisfy the manifest's exact requirement pins; both build
against HA's interpreter. Config-flow based: add via the HA UI and sign
in with the Amazon account after rebuild.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
EOF
)"
```
---
## Post-implementation (manual, by the user — not an automatable step)
After `sudo nixos-rebuild switch --flake '.#jupiter'`:
1. Settings → Devices & Services → Add Integration → **Alexa Media Player**.
2. Sign in with the Amazon account; complete any 2FA / app-password prompt in the UI flow.
3. Confirm media_player entities and sensors appear; test a TTS/announce service call to an Echo.
## Self-Review
- **Spec coverage:** goal (alexa_media_player packaging) → Task 1; alexapy bump → Step 1; dictor packaging → Step 1; component entry → Step 2; wrapt/packaging already-satisfied → included as deps in Step 2; build-time manifest check → Steps 4-5; runtime config-flow → Post-implementation. Deferred Alexa→HA scope: intentionally absent. No gaps.
- **Placeholder scan:** none — every step has concrete code/commands and the verified hashes.
- **Type/name consistency:** `haPython`, `dictor`, `alexapy` defined in Step 1 and referenced by those exact names in Step 2; domain `alexa_media` consistent throughout; hashes identical across plan, spec, and the verified build.
@@ -0,0 +1,234 @@
# DankMaterialShell (niri) Profile — Design
**Date:** 2026-07-24
**Branch:** `feat/dank-material-shell`
**Status:** Approved (brainstorming)
## Summary
Add a `my.profiles.dank` NixOS profile that provides a complete
[DankMaterialShell](https://danklinux.com) (DMS) desktop running on the
**niri** Wayland compositor, selectable at the SDDM login screen **alongside**
the existing KDE session on **mibook** (user `finn`).
DMS's keybind, spawn, and declarative-settings integration is delivered only
through home-manager modules, so this work also introduces home-manager into the
flake — as its own opt-in profile (`my.profiles.home-manager`) that the `dank`
profile enables as a dependency. Everything stays declarative inside the flake;
there is no separate home-manager entrypoint.
## Background / Research
DMS is a Quickshell-based Wayland desktop **shell** (bar, launcher, control
center, lock screen, notifications) — not a compositor. Its repository
(`github:AvengeMedia/DankMaterialShell`) ships a flake with:
- `nixosModules.dank-material-shell` — system side: installs the `dms-shell`
package + `quickshell`, a `dms` systemd **user** service, `dgop` (system
monitoring), matugen (dynamic theming), and enables polkit /
power-profiles-daemon / accounts-daemon / geoclue2. Configured via
`programs.dank-material-shell.*`.
- `homeModules.dank-material-shell` — home side: declarative
`~/.config/DankMaterialShell/settings.json`, the `dms` user service, plugin
management, and the `programs.quickshell` HM program.
- `homeModules.niri` — niri-specific integration: generates niri keybinds wired
to `dms ipc` (launcher, clipboard, notifications, media/brightness keys, power
menu, lock) and `spawn-at-startup` for `dms run`.
`homeModules.niri` builds on **niri-flake**'s home-manager API
(`programs.niri.settings`, `config.lib.niri.actions`); DMS does **not** bundle
niri-flake, so it must be added as its own input. quickshell ≥ 0.3.0 is
recommended and is available in nixos-unstable → use `pkgs.unstable.quickshell`.
### Key repo facts
- This repo is flake-parts based, pins `nixpkgs/nixos-26.05`, and exposes
`pkgs.unstable` via an overlay in `machines/configuration.nix`.
- `inputs` and `self` are already threaded into every NixOS module via
`_module.args` (set in `machines/configuration.nix`), so `modules/` files may
take `inputs` / `self` as arguments and `imports = [ inputs.<x>... ]`.
- The repo currently uses **no home-manager**; compositor profiles (e.g.
`hyprland`) install packages via `users.users.finn.packages`.
- mibook currently runs the KDE desktop (`my.profiles.kde-desktop`).
## Scope
- **In:** mibook only; niri+DMS as a session parallel to KDE; home-manager
scoped to user `finn`; a reusable `my.profiles.home-manager` module.
- **Out:** enabling on jupiter (headless server); Dank Greeter as the login
manager (SDDM stays); declarative DMS `settings.json` content (DMS is
configured through its own GUI at runtime; the HM `settings` option remains
available for later use but is left empty); any change to `configuration.nix`.
## Design
### 1. New flake inputs (`flake.nix`)
```nix
home-manager = {
url = "github:nix-community/home-manager";
inputs.nixpkgs.follows = "nixpkgs";
};
niri.url = "github:sodiboo/niri-flake";
dank.url = "github:AvengeMedia/DankMaterialShell";
```
Notes:
- `dank` tracks nixos-unstable internally (its own `nixpkgs`), which is expected
for the DMS package build.
- `niri-flake` provides both the compositor session (nixosModule) and the HM
`programs.niri.settings` API that DMS's niri module extends.
- `home-manager` follows the repo `nixpkgs` (nixos-26.05).
`machines/configuration.nix` is **not** modified — the existing
`_module.args.inputs = self.inputs` line already makes these inputs reachable
from any module.
### 2. Home-manager profile (`modules/environments/home-manager/default.nix`)
A new opt-in `my.profiles.home-manager` profile. Because module `imports` cannot
be gated on an option value, the home-manager NixOS module is imported
unconditionally (harmless — it only adds options and does nothing until
`home-manager.users.*` is populated); only the global settings are guarded by
`mkIf cfg.enable`:
```nix
{ config, lib, inputs, self, ... }:
let
cfg = config.my.profiles.home-manager;
in
{
imports = [ inputs.home-manager.nixosModules.home-manager ];
options.my.profiles.home-manager.enable =
lib.mkEnableOption "home-manager integration";
config = lib.mkIf cfg.enable {
home-manager.useGlobalPkgs = true; # HM shares the system pkgs (+ unstable overlay)
home-manager.useUserPackages = true;
home-manager.extraSpecialArgs = { inherit inputs self; };
};
}
```
Registered by adding `./environments/home-manager` to
`modules/environments/default.nix`.
> Placement note: the profile lives under `modules/environments/` (where
> `my.profiles.*` modules live) to match the namespace, even though its function
> is infrastructural.
### 3. Dank profile (`modules/environments/dank/default.nix`)
Standard profile pattern; enables the home-manager profile as a dependency and
splits configuration between the system module (session + daemons) and the
home-manager module (keybinds / spawn / settings):
```nix
{ config, lib, pkgs, inputs, ... }:
let
cfg = config.my.profiles.dank;
in
{
imports = [ inputs.dank.nixosModules.dank-material-shell ];
options.my.profiles.dank.enable = lib.mkEnableOption "DankMaterialShell on niri";
config = lib.mkIf cfg.enable {
# dependency: pull in home-manager integration
my.profiles.home-manager.enable = true;
# --- system side: niri session + DMS daemons/packages ---
programs.niri.enable = true; # niri-flake nixosModule → Wayland session in SDDM
programs.dank-material-shell = {
enable = true;
systemd.enable = true;
quickshell.package = pkgs.unstable.quickshell; # >= 0.3.0 from unstable
# enableSystemMonitoring / enableVPN / enableDynamicTheming / enableAudioWavelength
# / enableCalendarEvents all default true — left on.
};
# --- home side: DMS + niri keybinds for finn ---
home-manager.users.finn = {
imports = [
inputs.niri.homeModules.niri
inputs.dank.homeModules.dank-material-shell
inputs.dank.homeModules.niri
];
programs.dank-material-shell = {
enable = true;
systemd.enable = true;
quickshell.package = pkgs.unstable.quickshell;
niri.enableKeybinds = true; # Mod+Space launcher, Mod+V clipboard, media/brightness, power, lock…
niri.enableSpawn = true; # spawn `dms run` at niri startup
};
home.stateVersion = "26.05"; # match nixpkgs release; required by HM
};
};
}
```
Registered by adding `./environments/dank` to
`modules/environments/default.nix`.
Open validation point (resolve during implementation, not a blocker):
- Confirm the exact HM output name for the niri integration
(`homeModules.niri` vs `homeModules.dankMaterialShell.niri`) and that
`programs.niri.enable` is the correct niri-flake nixosModule option; adjust to
match the pinned input revisions.
- Confirm whether `programs.dank-material-shell.quickshell.package` needs to be
set on both the system and HM sides or only one; set consistently.
### 4. Enable on mibook (`machines/mibook/environments.nix`)
Add to the `my.profiles` block:
```nix
dank.enable = true;
```
KDE (`kde-desktop.enable = true`) stays; both sessions are offered by SDDM.
### 5. Documentation
No homepage dashboard entry (DMS is not a web service). CLAUDE.md is left
unchanged unless, after implementation, the home-manager pattern warrants a short
note — decided at the end, not up front (YAGNI).
## Data / control flow
1. `nixos-rebuild` builds the mibook toplevel; niri-flake registers a `niri`
Wayland session, DMS nixosModule installs packages + the `dms` user service
template, home-manager renders finn's niri config (with DMS keybinds) and DMS
config.
2. At login, SDDM lists **KDE** and **niri**. Selecting niri starts the
compositor; `spawn-at-startup` launches `dms run`, bringing up the DMS shell.
3. Keybinds invoke `dms ipc …` (launcher, clipboard, notifications, media,
brightness, power, lock). DMS is further configured via its own GUI, persisted
under `~/.config/DankMaterialShell/`.
## Risks / open questions
- **unstable/stable skew:** the repo pins nixos-26.05 while `dank` and
`niri-flake` track nixos-unstable, and quickshell comes from `pkgs.unstable`.
Qt6/quickshell version mismatch between the DMS package and the stable base is
the most likely failure. Mitigation: validate with a full toplevel build and,
if it fails, align quickshell/qt sourcing (e.g. take the DMS package's own
quickshell) before switching.
- **HM output/option names** may differ from the researched revision — pin the
inputs first, then read the resolved module options and adjust (see §3 open
validation point).
- **First HM activation** for finn: ensure `home.stateVersion` is set so the
build doesn't error.
## Verification
1. `nix flake check` succeeds.
2. `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
succeeds.
3. `sudo nixos-rebuild test --flake '.#mibook'`, then log into the **niri**
session: DMS bar appears, `Mod+Space` opens the launcher, KDE session still
works.
@@ -1,145 +0,0 @@
# Intel Quick Sync hardware transcoding for Jellyfin on jupiter
## Problem
Jellyfin streams stutter on jupiter whenever a client needs a transcode
(unsupported codec/container, bitrate cap, or a client that can't
direct-play). Transcoding currently runs entirely on CPU.
jupiter's Intel iGPU is already usable at the OS level:
- `hardware.graphics.enable = true` with `intel-media-driver` (the `iHD`
VAAPI driver) is configured in
`machines/jupiter/hardware-configuration.nix:20-27`.
- The commented-out `i915.force_probe = "9a49"` kernel param there
corresponds to a Quick-Sync-capable Intel UHD iGPU, confirming the
hardware supports it.
But `modules/environments/jellyfin/default.nix` never grants the
`jellyfin` systemd service access to `/dev/dri`, so Jellyfin has no path
to the GPU and silently falls back to software transcoding.
## Goal
Give the Jellyfin service access to the iGPU's VAAPI render node, so
Quick Sync can be enabled in Jellyfin's own dashboard and transcodes are
offloaded from the CPU.
## Non-goals
- Remote/external access or reverse-proxy tuning.
- General CPU/RAM headroom review of jupiter.
- A toggle option (`my.profiles.jellyfin.hardwareAcceleration.enable`) —
jupiter only has the one iGPU, so this is hardcoded on rather than
made configurable.
## Design
### NixOS change (declarative)
In `modules/environments/jellyfin/default.nix`, inside the existing
`config = lib.mkIf cfg.enable { ... }` block, grant the systemd service
supplementary access to the `video` and `render` groups (the groups that
own `/dev/dri/card*` and `/dev/dri/renderD*`):
```nix
systemd.services.jellyfin.serviceConfig.SupplementaryGroups = [
"video"
"render"
];
```
This is additive to the existing `systemd.services.jellyfin.after = [
"network-online.target" ];` block already in the file — both apply to
the same service.
Also add `libva-utils` to `environment.systemPackages` (or scoped to
this module) so `vainfo` is available on jupiter to verify the driver
loads correctly.
### Manual step (not declarative)
Jellyfin stores its transcoding/hardware-acceleration choice in its own
internal `encoding.xml`, which the NixOS module does not expose as an
option. After deploying the Nix change, one-time manual configuration in
the Jellyfin dashboard is required:
1. **Dashboard → Playback**.
2. Hardware acceleration: **Intel QuickSync (QSV)**.
3. VA-API device: `/dev/dri/renderD128`.
4. Enable hardware decoding for the codecs your library actually uses
(H264 at minimum; HEVC/VP9 depending on iGPU generation).
5. If any HDR content exists in the library, enable tone-mapping — this
is one of the more CPU-expensive operations Quick Sync can offload.
## Verification
Build-time (from the Mac, no SSH needed):
```
nix eval '.#nixosConfigurations.jupiter.config.systemd.services.jellyfin.serviceConfig.SupplementaryGroups' \
--extra-experimental-features 'nix-command flakes'
```
Expect `[ "video" "render" ]`.
On jupiter after `sudo nixos-rebuild switch --flake '.#jupiter'`:
```
systemctl status jellyfin
journalctl -u jellyfin -n 50 --no-pager
vainfo
```
`vainfo` should list the `iHD` driver and print supported VAEntrypoints
(VLD decode / encode profiles for H264/HEVC).
Functional check: play a file on a client that forces transcoding (or
force it manually via Jellyfin's playback quality setting), then in
Jellyfin's dashboard **Activity/Now Playing** panel confirm the
transcode reason and check that CPU usage on jupiter (`htop`) stays low
during playback rather than pegging a core — Quick Sync offload should
show up as low CPU, some GPU (`intel_gpu_top`) activity instead.
## Open items
- Exact supported codec list depends on the iGPU generation (device ID
`9a49`) — confirm via `vainfo` output once run, and enable only the
hardware decode paths it actually reports.
## Post-deploy fix: two additional runtime packages required
After the initial deploy (Task 1's `SupplementaryGroups` grant) and
enabling QSV in the dashboard, HEVC HDR playback hung indefinitely
(Direct Play worked for some titles; titles that needed a real
transcode+tonemap never produced output). Root-caused via
`journalctl -u jellyfin` and the per-session ffmpeg transcode log
(`find / -xdev -iname '*ffmpeg-transcode*'`) — two separate runtimes
were missing beyond `intel-media-driver` (which only provides VAAPI):
1. **QSV session creation failed:** `Error creating a MFX session: -9`
/ `Error initializing an MFX session: -3` on
`-init_hw_device qsv=qs@va`. VAAPI and QSV are separate runtimes on
Linux — QSV needs the oneVPL/MFX GPU implementation. Fix: added
`pkgs.vpl-gpu-rt` ("oneAPI Video Processing Library Intel GPU
implementation"; note `onevpl-intel-gpu` is the old, renamed
attribute) to `hardware.graphics.extraPackages` in
`machines/jupiter/hardware-configuration.nix`.
2. **OpenCL device creation failed:** `Failed to get number of OpenCL
platforms: -1001` (`CL_PLATFORM_NOT_FOUND_KHR`) on
`-init_hw_device opencl=ocl@va`. The `tonemap_opencl` filter jellyfin
uses for HDR→SDR tone-mapping needs a working OpenCL ICD, which
nothing installed so far provides. Fix: added
`pkgs.intel-compute-runtime` ("Intel Graphics Compute Runtime oneAPI
Level Zero and OpenCL, supporting 12th Gen and newer" — matches
jupiter's Tiger Lake/Xe iGPU) to the same `extraPackages` list.
Confirmed working end-to-end: HEVC HDR transcode with QSV encode +
OpenCL tone-map runs at `speed=2.68x` realtime on jupiter's iGPU, and
plays smoothly on Apple TV (JellyTV app).
Both packages live in `machines/jupiter/hardware-configuration.nix`
(`hardware.graphics.extraPackages`), alongside `intel-media-driver`,
rather than in the jellyfin module itself — they're iGPU runtime
capabilities, not something specific to the jellyfin service.
@@ -1,152 +0,0 @@
# Amazon Alexa integration for Home Assistant (jupiter) — design
**Date:** 2026-07-29
**Machine:** jupiter
**Status:** approved, ready for implementation plan
## Goal
Let Home Assistant control and read the household Amazon Echo devices via the
unofficial [`alexa_media_player`](https://github.com/Alandtse/alexa_media_player)
integration: text-to-speech / announcements, media control, and per-device
sensors (last-called device, next alarm/timer, DND state, etc.).
This uses the user's Amazon account through an unofficial API. It is a
config-flow integration: after the rebuild it is added through the HA UI, not
via YAML.
## Non-goals (deferred)
Alexa → HA voice control ("Alexa, turn on the light") is **out of scope**. It
would need either `emulated_hue` bound to port 80 on the LAN, or a public HTTPS
endpoint plus the AWS-Lambda Smart Home Skill. The user chose to decide on that
later. Nothing in this change touches the firewall, port 80, systemd unit
capabilities, or network exposure.
## Approach
Package the integration declaratively, following the existing `ha-sourdough`
pattern in `modules/environments/home-assistant/default.nix` (a
`buildHomeAssistantComponent` entry in `services.home-assistant.customComponents`).
No HACS runtime.
Unlike sourdough, `alexa_media_player` has real Python dependencies. Its
`manifest.json` (v5.15.7) declares:
```
alexapy==1.29.25
packaging>=20.3
wrapt>=1.14.0
dictor>=0.1.12,<0.2
```
`buildHomeAssistantComponent` runs `manifestCheckPhase` at build time
(`check_manifest.py`): every requirement must resolve to an installed
distribution **whose version satisfies the specifier**, or the build fails.
Home Assistant repeats this check at runtime. Therefore each requirement must be
satisfied exactly — the exact `==1.29.25` pin in particular.
Dependency status in the pinned nixpkgs (`nixos-25.11`):
| Requirement | nixpkgs today | Action |
| ---------------------- | ------------- | --------------------------------------- |
| `alexapy==1.29.25` | 1.29.22 | **Bump** to 1.29.25 via override |
| `dictor>=0.1.12,<0.2` | *absent* | **Package** dictor 0.1.12 (new) |
| `wrapt>=1.14.0` | 1.17.2 | none — already satisfied |
| `packaging>=20.3` | 26.1 | none — already satisfied |
`authcaptureproxy` (in nixpkgs at 1.3.7) is a transitive dependency of
`alexapy`, not listed in the manifest, so it needs no direct handling.
## Components
All changes live in `modules/environments/home-assistant/default.nix` (plus the
hashes below). Three small pieces, wired together in the module's `let` block:
### 1. `dictor` package (new)
Not in nixpkgs. Pure-Python, no runtime dependencies (`requires_dist: null`),
ships a `setup.py`. A minimal `pkgs.python3Packages.buildPythonPackage`:
- pname `dictor`, version `0.1.12`
- `src = fetchPypi { pname = "dictor"; version = "0.1.12"; hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs="; }`
- setuptools format (legacy `setup.py`); `build-system = [ setuptools ]`
- `doCheck = false` (no meaningful test suite); `pythonImportsCheck = [ "dictor" ]`
Build against the HA Python set so the version lands in HA's venv — i.e. use
`config.services.home-assistant.package.python.pkgs` (the same interpreter the
component check and HA runtime use), not the top-level `pkgs.python3Packages`.
### 2. `alexapy` 1.29.25 (override)
nixpkgs `alexapy` is fetched from **GitLab** (`keatontaylor/alexapy`, tag
`v<version>`), not PyPI. Override just the version + src via
`overridePythonAttrs`, reusing the existing build-system and dependency list:
- `version = "1.29.25"`
- `src = fetchFromGitLab { owner = "keatontaylor"; repo = "alexapy"; tag = "v1.29.25"; hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4="; }`
This is a patch bump (1.29.22 → 1.29.25); the dependency set is expected to be
unchanged. Override the HA-Python-set `alexapy` so it shares the interpreter
with dictor and the component.
### 3. `alexa_media_player` component (new `customComponents` entry)
```
buildHomeAssistantComponent {
owner = "Alandtse";
domain = "alexa_media";
version = "5.15.7";
src = fetchFromGitHub {
owner = "Alandtse";
repo = "alexa_media_player";
rev = "v5.15.7";
hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=";
};
dependencies = [ alexapy' dictor' wrapt packaging ]; # HA-python-set packages
}
```
`dependencies` must make every manifest requirement importable at the required
version for `manifestCheckPhase` to pass. Include all four (the two custom ones
plus `wrapt` and `packaging` from the HA Python set) to be explicit.
## Data flow
1. `nixos-rebuild switch` builds the component; `manifestCheckPhase` validates
the four requirements against the provided `dependencies`.
2. HA starts; the custom component is present but not configured.
3. User adds **Alexa Media Player** in Settings → Devices & Services, signs in
with the Amazon account (email/password; 2FA or app-password handled in the
UI flow at runtime).
4. HA creates media_player entities and per-device sensors; TTS/announce
services become available for automations.
## Error handling / risks
- **Version-pin drift.** If a future `alexa_media_player` bump changes the
`alexapy==` pin, `alexapy` must be re-bumped in lockstep, or the build fails
loudly at `manifestCheckPhase` (fail-safe, not silent).
- **Amazon login fragility.** The unofficial API can break on Amazon's side
(captcha/2FA changes). This is a runtime concern, independent of packaging;
not addressed here.
- **`dictor` upper bound `<0.2`.** 0.1.12 is the current release and satisfies
it. If nixpkgs later gains a `dictor` ≥ 0.2, prefer our pinned 0.1.12 for
this component.
## Verification
- `nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel'`
succeeds — this exercises the build-time manifest-requirements check for all
three new/overridden derivations.
- `nixfmt-rfc-style` clean on the edited module.
- Post-deploy (manual, by the user): the integration appears under Add
Integration, and a TTS/announce call reaches an Echo.
## Pinned artifacts
| Artifact | Source | Ref / version | Hash |
| --------------------------- | ---------- | ------------- | ------------------------------------------------- |
| alexa_media_player | GitHub | v5.15.7 | sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI= |
| alexapy | GitLab | v1.29.25 | sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4= |
| dictor | PyPI sdist | 0.1.12 | sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs= |
Generated
+225 -12
View File
@@ -1,5 +1,41 @@
{ {
"nodes": { "nodes": {
"dank": {
"inputs": {
"dank-qml-common": "dank-qml-common",
"flake-compat": "flake-compat",
"nixpkgs": "nixpkgs"
},
"locked": {
"lastModified": 1784830217,
"narHash": "sha256-6MvMw45RSORjINmFd3Lfz9VX9sH8+xTb5WNZiWIKbDw=",
"owner": "AvengeMedia",
"repo": "DankMaterialShell",
"rev": "8af71036cca800064f3fb22dd201109ade6c5ee9",
"type": "github"
},
"original": {
"owner": "AvengeMedia",
"repo": "DankMaterialShell",
"type": "github"
}
},
"dank-qml-common": {
"flake": false,
"locked": {
"lastModified": 1784647395,
"narHash": "sha256-kcLSJC8XBzmWoSBc90Zn81qrNsqWMkwQ1m/zZixOw30=",
"owner": "AvengeMedia",
"repo": "dank-qml-common",
"rev": "1919595f0dde4f5bf5ac0baa1902ff6d070971d5",
"type": "github"
},
"original": {
"owner": "AvengeMedia",
"repo": "dank-qml-common",
"type": "github"
}
},
"flake-compat": { "flake-compat": {
"flake": false, "flake": false,
"locked": { "locked": {
@@ -16,6 +52,22 @@
"type": "github" "type": "github"
} }
}, },
"flake-compat_2": {
"flake": false,
"locked": {
"lastModified": 1767039857,
"narHash": "sha256-vNpUSpF5Nuw8xvDLj2KCwwksIbjua2LZCqhV1LNRDns=",
"owner": "NixOS",
"repo": "flake-compat",
"rev": "5edf11c44bc78a0d334f6334cdaf7d60d732daab",
"type": "github"
},
"original": {
"owner": "NixOS",
"repo": "flake-compat",
"type": "github"
}
},
"flake-parts": { "flake-parts": {
"inputs": { "inputs": {
"nixpkgs-lib": "nixpkgs-lib" "nixpkgs-lib": "nixpkgs-lib"
@@ -79,12 +131,89 @@
"type": "github" "type": "github"
} }
}, },
"home-manager": {
"inputs": {
"nixpkgs": [
"nixpkgs"
]
},
"locked": {
"lastModified": 1784350909,
"narHash": "sha256-ZWyzLbS1yKUTeFJLmdVuWNnHttL333/ldJbEE+KzCrM=",
"owner": "nix-community",
"repo": "home-manager",
"rev": "4ce190229c73d44536caa7072f6308fb2d8feeb3",
"type": "github"
},
"original": {
"owner": "nix-community",
"ref": "release-26.05",
"repo": "home-manager",
"type": "github"
}
},
"niri": {
"inputs": {
"niri-stable": "niri-stable",
"niri-unstable": "niri-unstable",
"nixpkgs": "nixpkgs_2",
"nixpkgs-stable": "nixpkgs-stable",
"xwayland-satellite-stable": "xwayland-satellite-stable",
"xwayland-satellite-unstable": "xwayland-satellite-unstable"
},
"locked": {
"lastModified": 1784874881,
"narHash": "sha256-u4jhSIf/Un0qZB+Cn3hTTaHSI20XeAxYbA5o4faqdJs=",
"owner": "sodiboo",
"repo": "niri-flake",
"rev": "ef7a2a3d719af46b906c22a3ebfb7d65627b2cd2",
"type": "github"
},
"original": {
"owner": "sodiboo",
"repo": "niri-flake",
"type": "github"
}
},
"niri-stable": {
"flake": false,
"locked": {
"lastModified": 1756556321,
"narHash": "sha256-RLD89dfjN0RVO86C/Mot0T7aduCygPGaYbog566F0Qo=",
"owner": "YaLTeR",
"repo": "niri",
"rev": "01be0e65f4eb91a9cd624ac0b76aaeab765c7294",
"type": "github"
},
"original": {
"owner": "YaLTeR",
"ref": "v25.08",
"repo": "niri",
"type": "github"
}
},
"niri-unstable": {
"flake": false,
"locked": {
"lastModified": 1784570726,
"narHash": "sha256-9EMn69JBcFWFgUM7f0VBAX+jBby5b9H3M59U75+5yI4=",
"owner": "YaLTeR",
"repo": "niri",
"rev": "7f26c3ee804fb6ed458ef7fb0e3c794f14e0b3bc",
"type": "github"
},
"original": {
"owner": "YaLTeR",
"repo": "niri",
"type": "github"
}
},
"nix": { "nix": {
"inputs": { "inputs": {
"flake-compat": "flake-compat", "flake-compat": "flake-compat_2",
"flake-parts": "flake-parts_2", "flake-parts": "flake-parts_2",
"git-hooks-nix": "git-hooks-nix", "git-hooks-nix": "git-hooks-nix",
"nixpkgs": "nixpkgs", "nixpkgs": "nixpkgs_3",
"nixpkgs-23-11": "nixpkgs-23-11", "nixpkgs-23-11": "nixpkgs-23-11",
"nixpkgs-regression": "nixpkgs-regression" "nixpkgs-regression": "nixpkgs-regression"
}, },
@@ -140,7 +269,7 @@
}, },
"nixos-hardware": { "nixos-hardware": {
"inputs": { "inputs": {
"nixpkgs": "nixpkgs_2" "nixpkgs": "nixpkgs_4"
}, },
"locked": { "locked": {
"lastModified": 1784723954, "lastModified": 1784723954,
@@ -158,15 +287,18 @@
}, },
"nixpkgs": { "nixpkgs": {
"locked": { "locked": {
"lastModified": 1783148766, "lastModified": 1783224372,
"narHash": "sha256-H9+N+GFtsbVC8ZniHliChM7ndizxtqVZs6bnGOLM3WQ=", "narHash": "sha256-8i/87eeoqiGE4yOTjwSA3Eh/ziJRQEmd/unYU+K27sk=",
"rev": "a50de1b7d8a586adc18d2395c19de7d6058e6030", "owner": "nixos",
"type": "tarball", "repo": "nixpkgs",
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.4193.a50de1b7d8a5/nixexprs.tar.xz" "rev": "d407951447dcd00442e97087bf374aad70c04cea",
"type": "github"
}, },
"original": { "original": {
"type": "tarball", "owner": "nixos",
"url": "https://channels.nixos.org/nixos-26.05/nixexprs.tar.xz" "ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
} }
}, },
"nixpkgs-23-11": { "nixpkgs-23-11": {
@@ -216,6 +348,22 @@
"type": "github" "type": "github"
} }
}, },
"nixpkgs-stable": {
"locked": {
"lastModified": 1782847189,
"narHash": "sha256-twXPFqFsrrY5r28Zh7Homgcp2gUMBgQ6WDS98Q/3xFI=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "b6018f87da91d19d0ab4cf979885689b469cdd41",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixos-25.11",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs-unstable": { "nixpkgs-unstable": {
"locked": { "locked": {
"lastModified": 1784796856, "lastModified": 1784796856,
@@ -231,6 +379,35 @@
} }
}, },
"nixpkgs_2": { "nixpkgs_2": {
"locked": {
"lastModified": 1784796856,
"narHash": "sha256-wWFrV5/Qbm+lyt5x20E/bSbfJiGKMo4RCxZV8cl/WZI=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "e2587caef70cea85dd97d7daab492899902dbf5d",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs_3": {
"locked": {
"lastModified": 1783148766,
"narHash": "sha256-H9+N+GFtsbVC8ZniHliChM7ndizxtqVZs6bnGOLM3WQ=",
"rev": "a50de1b7d8a586adc18d2395c19de7d6058e6030",
"type": "tarball",
"url": "https://releases.nixos.org/nixos/26.05/nixos-26.05.4193.a50de1b7d8a5/nixexprs.tar.xz"
},
"original": {
"type": "tarball",
"url": "https://channels.nixos.org/nixos-26.05/nixexprs.tar.xz"
}
},
"nixpkgs_4": {
"locked": { "locked": {
"lastModified": 1767892417, "lastModified": 1767892417,
"narHash": "sha256-8bW3q88CEg2u4hSP66Vf4lpbLonHz7hqDNBMcCY7E9U=", "narHash": "sha256-8bW3q88CEg2u4hSP66Vf4lpbLonHz7hqDNBMcCY7E9U=",
@@ -243,7 +420,7 @@
"url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz" "url": "https://channels.nixos.org/nixos-unstable/nixexprs.tar.xz"
} }
}, },
"nixpkgs_3": { "nixpkgs_5": {
"locked": { "locked": {
"lastModified": 1784707089, "lastModified": 1784707089,
"narHash": "sha256-DUedXhD2Rg8q4Xyd07Sb90eZGy4gg6W+Vl/WbLNwAZo=", "narHash": "sha256-DUedXhD2Rg8q4Xyd07Sb90eZGy4gg6W+Vl/WbLNwAZo=",
@@ -259,13 +436,49 @@
}, },
"root": { "root": {
"inputs": { "inputs": {
"dank": "dank",
"flake-parts": "flake-parts", "flake-parts": "flake-parts",
"home-manager": "home-manager",
"niri": "niri",
"nix": "nix", "nix": "nix",
"nixos-generators": "nixos-generators", "nixos-generators": "nixos-generators",
"nixos-hardware": "nixos-hardware", "nixos-hardware": "nixos-hardware",
"nixpkgs": "nixpkgs_3", "nixpkgs": "nixpkgs_5",
"nixpkgs-unstable": "nixpkgs-unstable" "nixpkgs-unstable": "nixpkgs-unstable"
} }
},
"xwayland-satellite-stable": {
"flake": false,
"locked": {
"lastModified": 1755491097,
"narHash": "sha256-m+9tUfsmBeF2Gn4HWa6vSITZ4Gz1eA1F5Kh62B0N4oE=",
"owner": "Supreeeme",
"repo": "xwayland-satellite",
"rev": "388d291e82ffbc73be18169d39470f340707edaa",
"type": "github"
},
"original": {
"owner": "Supreeeme",
"ref": "v0.7",
"repo": "xwayland-satellite",
"type": "github"
}
},
"xwayland-satellite-unstable": {
"flake": false,
"locked": {
"lastModified": 1784679892,
"narHash": "sha256-Mb7jpqnrcYCfNSItIkkHpuR3YxWFxPuIBfcwNKlRBkk=",
"owner": "Supreeeme",
"repo": "xwayland-satellite",
"rev": "8d135d3b2854b30fd01ea6cd6c27e523dd50a839",
"type": "github"
},
"original": {
"owner": "Supreeeme",
"repo": "xwayland-satellite",
"type": "github"
}
} }
}, },
"root": "root", "root": "root",
+6
View File
@@ -11,6 +11,12 @@
url = "github:nix-community/nixos-generators"; url = "github:nix-community/nixos-generators";
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
}; };
home-manager = {
url = "github:nix-community/home-manager/release-26.05";
inputs.nixpkgs.follows = "nixpkgs";
};
niri.url = "github:sodiboo/niri-flake";
dank.url = "github:AvengeMedia/DankMaterialShell";
}; };
@@ -35,8 +35,6 @@
#vaapiIntel # LIBVA_DRIVER_NAME=i965 (older but works better for Firefox/Chromium) #vaapiIntel # LIBVA_DRIVER_NAME=i965 (older but works better for Firefox/Chromium)
libva-vdpau-driver libva-vdpau-driver
libvdpau-va-gl libvdpau-va-gl
vpl-gpu-rt # oneVPL/MFX runtime, required for QSV (h264_qsv/hevc_qsv) session creation
intel-compute-runtime # OpenCL runtime, required for tonemap_opencl (HDR tone-mapping)
]; ];
}; };
+1
View File
@@ -6,6 +6,7 @@ in
{ {
my.profiles = { my.profiles = {
kde-desktop.enable = true; kde-desktop.enable = true;
dank.enable = false;
zsh.enable = true; zsh.enable = true;
apps = { apps = {
desktop_apps = true; desktop_apps = true;
+48
View File
@@ -0,0 +1,48 @@
{
config,
lib,
pkgs,
inputs,
self,
...
}:
let
cfg = config.my.profiles.dank;
in
{
imports = [ self.inputs.dank.nixosModules.dank-material-shell ];
options.my.profiles.dank.enable = lib.mkEnableOption "DankMaterialShell on niri";
config = lib.mkIf cfg.enable {
# Dependency: declarative user config comes from home-manager.
my.profiles.home-manager.enable = true;
# System side: niri Wayland session + DMS daemons/packages.
programs.niri.enable = true;
programs.dank-material-shell = {
enable = true;
systemd.enable = true;
quickshell.package = pkgs.unstable.quickshell;
};
# Home side: DMS shell + niri spawn for finn (keybinds come via includes).
home-manager.users.finn = {
imports = [
inputs.niri.homeModules.niri
inputs.dank.homeModules.dank-material-shell
inputs.dank.homeModules.niri
];
programs.dank-material-shell = {
enable = true;
systemd.enable = true;
quickshell.package = pkgs.unstable.quickshell;
niri.enableSpawn = true;
};
home.stateVersion = "26.05";
};
};
}
+2
View File
@@ -8,6 +8,8 @@
./development ./development
./home-assistant ./home-assistant
./hyprland ./hyprland
./home-manager
./dank
./zsh ./zsh
./paperless ./paperless
./prowlarr ./prowlarr
@@ -9,39 +9,6 @@
let let
cfg = config.my.profiles.home-assistant; cfg = config.my.profiles.home-assistant;
hostName = config.networking.hostName; hostName = config.networking.hostName;
# Python deps for the alexa_media_player custom component. Built against
# Home Assistant's own interpreter — the same set buildHomeAssistantComponent
# uses — so HA's build-time and runtime manifest-requirement checks pass.
haPython = pkgs.home-assistant.python3Packages;
# dictor is not in nixpkgs; alexa_media_player needs dictor>=0.1.12,<0.2.
# Pure-Python, no runtime deps, legacy setup.py.
dictor = haPython.buildPythonPackage {
pname = "dictor";
version = "0.1.12";
format = "setuptools";
src = haPython.fetchPypi {
pname = "dictor";
version = "0.1.12";
hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs=";
};
build-system = [ haPython.setuptools ];
doCheck = false;
pythonImportsCheck = [ "dictor" ];
};
# nixpkgs ships alexapy 1.29.22; the manifest pins ==1.29.25. Patch bump.
# nixpkgs fetches alexapy from GitLab (keatontaylor/alexapy), tag v<version>.
alexapy = haPython.alexapy.overridePythonAttrs (old: {
version = "1.29.25";
src = pkgs.fetchFromGitLab {
owner = "keatontaylor";
repo = "alexapy";
tag = "v1.29.25";
hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4=";
};
});
in in
{ {
@@ -56,42 +23,6 @@ in
services.home-assistant = { services.home-assistant = {
enable = true; enable = true;
openFirewall = true; openFirewall = true;
# HACS-style custom components, packaged declaratively (no HACS runtime).
# Config-flow based: add via Settings > Devices & Services after rebuild.
customComponents = [
(pkgs.buildHomeAssistantComponent {
owner = "Matts-Baps";
domain = "sourdough";
version = "1.1.3";
src = pkgs.fetchFromGitHub {
owner = "Matts-Baps";
repo = "ha-sourdough";
rev = "v1.1.3";
hash = "sha256-Uoid/2f6GxZMuE5Keu2VjHPYuOxnYG8hsCD6BYcaTvM=";
};
})
(pkgs.buildHomeAssistantComponent {
owner = "Alandtse";
domain = "alexa_media";
version = "5.15.7";
src = pkgs.fetchFromGitHub {
owner = "Alandtse";
repo = "alexa_media_player";
rev = "v5.15.7";
hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=";
};
# Every manifest requirement must be importable at a satisfying
# version or manifestCheckPhase fails the build.
dependencies = [
alexapy
dictor
haPython.wrapt
haPython.packaging
];
})
];
extraComponents = [ extraComponents = [
"matter" "matter"
"mobile_app" "mobile_app"
@@ -0,0 +1,21 @@
{
config,
lib,
inputs,
self,
...
}:
let
cfg = config.my.profiles.home-manager;
in
{
imports = [ self.inputs.home-manager.nixosModules.home-manager ];
options.my.profiles.home-manager.enable = lib.mkEnableOption "home-manager integration";
config = lib.mkIf cfg.enable {
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
home-manager.extraSpecialArgs = { inherit inputs self; };
};
}
@@ -22,8 +22,6 @@ in
openFirewall = true; openFirewall = true;
}; };
environment.systemPackages = [ pkgs.libva-utils ];
my.homepage.services = [ my.homepage.services = [
{ {
group = "Media"; group = "Media";
@@ -36,10 +34,6 @@ in
systemd.services.jellyfin = { systemd.services.jellyfin = {
after = [ "network-online.target" ]; after = [ "network-online.target" ];
serviceConfig.SupplementaryGroups = [
"video"
"render"
];
}; };
}; };
} }