# 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