165 lines
5.3 KiB
Markdown
165 lines
5.3 KiB
Markdown
# Homepage Widgets 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.homepage.widgets` NixOS option so widgets can be declared in the homepage module and contributed from other modules, mirroring how `my.homepage.services` works today.
|
||
|
||
**Architecture:** Add a `my.homepage.widgets` option (typed `listOf attrs` since widget shapes vary by type) to the homepage module, import a `manual-widgets.nix` for ad-hoc definitions, merge both and pass to `services.homepage-dashboard.widgets`. Add starter widgets in `machines/jupiter/environments.nix` to confirm the wiring works end-to-end.
|
||
|
||
**Tech Stack:** Nix, NixOS module system, gethomepage.dev (`services.homepage-dashboard`)
|
||
|
||
---
|
||
|
||
## File Map
|
||
|
||
| Action | File | Responsibility |
|
||
|--------|------|----------------|
|
||
| Modify | `modules/environments/homepage/default.nix` | Add `my.homepage.widgets` option + wire to dashboard |
|
||
| Create | `modules/environments/homepage/manual-widgets.nix` | Empty list for ad-hoc widgets (parallel to `manual-services.nix`) |
|
||
| Modify | `machines/jupiter/environments.nix` | Declare starter widgets to verify the feature end-to-end |
|
||
|
||
---
|
||
|
||
### Task 1: Add `my.homepage.widgets` option to the homepage module
|
||
|
||
**Files:**
|
||
- Modify: `modules/environments/homepage/default.nix`
|
||
- Create: `modules/environments/homepage/manual-widgets.nix`
|
||
|
||
- [ ] **Step 1: Create `manual-widgets.nix`** — empty list, same pattern as `manual-services.nix`
|
||
|
||
```nix
|
||
# modules/environments/homepage/manual-widgets.nix
|
||
[ ]
|
||
```
|
||
|
||
- [ ] **Step 2: Add `manualWidgets` import in the `let` block of `default.nix`**
|
||
|
||
Current `let` block (lines 7–42) ends with `homepageServices`. Add one line after `manualServices`:
|
||
|
||
```nix
|
||
manualServices = import ./manual-services.nix;
|
||
manualWidgets = import ./manual-widgets.nix;
|
||
```
|
||
|
||
- [ ] **Step 3: Add the `my.homepage.widgets` option**
|
||
|
||
After the closing brace of `options.my.homepage.services` (line 80), add:
|
||
|
||
```nix
|
||
options.my.homepage.widgets = with lib; mkOption {
|
||
type = types.listOf types.attrs;
|
||
default = [ ];
|
||
description = "Widget definitions passed directly to services.homepage-dashboard.widgets. Each entry is an attrset like { resources = { cpu = true; memory = true; }; }.";
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 4: Wire widgets to the dashboard in the `config` block**
|
||
|
||
The `config` block currently sets `services = homepageServices ++ manualServices;`. Add `widgets`:
|
||
|
||
```nix
|
||
config = lib.mkIf cfg.enable {
|
||
services.homepage-dashboard = {
|
||
enable = true;
|
||
listenPort = dashboardPort;
|
||
allowedHosts = "${dashboardHost}:${toString dashboardPort},localhost:${toString dashboardPort},127.0.0.1:${toString dashboardPort},jupiter.solar.internal:${toString dashboardPort}";
|
||
bookmarks = import ./bookmarks.nix;
|
||
services = homepageServices ++ manualServices;
|
||
widgets = config.my.homepage.widgets ++ manualWidgets;
|
||
};
|
||
# ... rest of config unchanged
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 5: Build to check for eval errors (no switch yet)**
|
||
|
||
```bash
|
||
nixos-rebuild build --flake /Users/finnmarkwitz/development/nixos#jupiter 2>&1 | tail -20
|
||
```
|
||
|
||
Expected: build succeeds with no errors (widgets list is empty, so no visible change yet).
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
cd /Users/finnmarkwitz/development/nixos
|
||
git add modules/environments/homepage/default.nix modules/environments/homepage/manual-widgets.nix
|
||
git commit -m "feat: add my.homepage.widgets option to homepage module"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Add starter widgets in `environments.nix`
|
||
|
||
**Files:**
|
||
- Modify: `machines/jupiter/environments.nix`
|
||
|
||
- [ ] **Step 1: Add `my.homepage.widgets` to `environments.nix`**
|
||
|
||
Add the following after the `my.profiles` block (e.g. after line 39, before the `my.hardware` block):
|
||
|
||
```nix
|
||
my.homepage.widgets = [
|
||
{
|
||
search = {
|
||
provider = "google";
|
||
target = "_blank";
|
||
};
|
||
}
|
||
{
|
||
resources = {
|
||
cpu = true;
|
||
memory = true;
|
||
disk = "/";
|
||
cacheInterval = 5000;
|
||
};
|
||
}
|
||
{
|
||
datetime = {
|
||
text_size = "xl";
|
||
format = {
|
||
timeStyle = "short";
|
||
dateStyle = "short";
|
||
hour12 = false;
|
||
};
|
||
};
|
||
}
|
||
];
|
||
```
|
||
|
||
- [ ] **Step 2: Build to confirm eval**
|
||
|
||
```bash
|
||
nixos-rebuild build --flake /Users/finnmarkwitz/development/nixos#jupiter 2>&1 | tail -20
|
||
```
|
||
|
||
Expected: build succeeds.
|
||
|
||
- [ ] **Step 3: Switch and verify visually**
|
||
|
||
```bash
|
||
sudo nixos-rebuild switch --flake /Users/finnmarkwitz/development/nixos#jupiter
|
||
```
|
||
|
||
Open `http://jupiter.solar.internal:8082` (or `http://localhost:8082`) in a browser.
|
||
|
||
Expected: search bar, CPU/memory/disk resource monitor, and date/time widget appear at the top of the dashboard.
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
cd /Users/finnmarkwitz/development/nixos
|
||
git add machines/jupiter/environments.nix
|
||
git commit -m "feat: add starter homepage widgets (search, resources, datetime)"
|
||
```
|
||
|
||
---
|
||
|
||
## Verification Checklist
|
||
|
||
- [ ] `nixos-rebuild build` passes with no eval errors
|
||
- [ ] Dashboard at `:8082` shows widgets at top of page
|
||
- [ ] Existing services and bookmarks are unchanged
|
||
- [ ] Other modules can now contribute widgets via `my.homepage.widgets = [ ... ];` in their `config` block
|