# ntfy Notification 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:** Add a `my.profiles.ntfy` NixOS module that runs an auth-required self-hosted ntfy server on jupiter, exposes a homepage tile, and wires a Home Assistant `rest_command` for publishing notifications.

**Architecture:** A single profile module under `modules/environments/ntfy/`, following the repo's `my.profiles.<name>` pattern. It configures `services.ntfy-sh` with `auth-default-access = deny-all`, opens the firewall, registers a homepage tile, and — when the home-assistant profile is enabled — merges a `rest_command.ntfy_send` into `services.home-assistant.config`. No secrets touch the Nix store; credentials are provisioned manually by the operator, and the only secret lives in HA's `secrets.yaml`.

**Tech Stack:** Nix (flake-parts NixOS config), nixpkgs `services.ntfy-sh`, `services.home-assistant`, nixfmt-rfc-style.

## Global Constraints

- Follow the profile pattern exactly: `let cfg = config.my.profiles.<name>; in { options.my.profiles.<name>.enable = lib.mkEnableOption "..."; config = lib.mkIf cfg.enable { ... }; }`.
- Namespace is `my.profiles.ntfy`.
- Homepage self-registration uses `my.homepage.services` (list of `{ group; name; description; href; icon; }`).
- `hostName` is bound from `config.networking.hostName`, matching sibling modules.
- All `.nix` files must be formatted with `nixfmt-rfc-style`.
- No secret values may appear in any `.nix` file (nothing enters the Nix store). The only secret is `ntfy_password` in `/var/lib/hass/secrets.yaml`, provisioned by hand.
- Evaluation check used throughout (runs on darwin without a Linux builder):
  `nix eval '.#nixosConfigurations.jupiter.config.system.build.toplevel.drvPath'`
- Do NOT run `nixos-rebuild` or SSH to jupiter; deploy + provisioning are operator steps the user runs on the host.

---

### Task 1: Create the ntfy server module (server + homepage tile)

**Files:**
- Create: `modules/environments/ntfy/default.nix`
- Modify: `modules/environments/default.nix` (add `./ntfy` to `imports`)
- Modify: `machines/jupiter/environments.nix` (enable the profile)

**Interfaces:**
- Consumes: `config.networking.hostName`; `services.ntfy-sh` (nixpkgs); `my.homepage.services` (repo homepage module).
- Produces: option `my.profiles.ntfy.enable` (bool), `my.profiles.ntfy.port` (port, default 2586), `my.profiles.ntfy.topic` (str, default "ha"), `my.profiles.ntfy.haIntegration.enable` (bool, default true). Later tasks rely on `cfg.port`, `cfg.topic`, and `cfg.haIntegration.enable`.

- [ ] **Step 1: Create the module file**

Create `modules/environments/ntfy/default.nix`:

```nix
# self-hosted push notification server (ntfy)
{
  config,
  lib,
  ...
}:
let
  cfg = config.my.profiles.ntfy;
  hostName = config.networking.hostName;
in
{
  options.my.profiles.ntfy = with lib; {
    enable = mkEnableOption "ntfy notification server";

    port = mkOption {
      type = types.port;
      default = 2586;
      description = "HTTP port ntfy listens on.";
    };

    topic = mkOption {
      type = types.str;
      default = "ha";
      description = "Topic Home Assistant publishes notifications to.";
    };

    haIntegration.enable = mkOption {
      type = types.bool;
      default = true;
      description = "Wire a Home Assistant rest_command that publishes to ntfy.";
    };
  };

  config = lib.mkIf cfg.enable {
    services.ntfy-sh = {
      enable = true;
      settings = {
        base-url = "http://${hostName}:${toString cfg.port}";
        listen-http = ":${toString cfg.port}";
        auth-file = "/var/lib/ntfy-sh/user.db";
        auth-default-access = "deny-all";
      };
    };

    networking.firewall.allowedTCPPorts = [ cfg.port ];

    my.homepage.services = [
      {
        group = "Services";
        name = "ntfy";
        description = "Push notifications";
        href = "http://${hostName}:${toString cfg.port}";
        icon = "ntfy.svg";
      }
    ];
  };
}
```

- [ ] **Step 2: Register the module in the environments import list**

In `modules/environments/default.nix`, add `./ntfy` to the `imports` list (place it near the other service modules, e.g. after `./home-assistant`):

```nix
    ./home-assistant
    ./ntfy
```

- [ ] **Step 3: Enable the profile on jupiter**

In `machines/jupiter/environments.nix`, inside the `my.profiles = { ... }` block, add:

```nix
    ntfy.enable = true;
```

- [ ] **Step 4: Format the new file**

Run: `nixfmt-rfc-style modules/environments/ntfy/default.nix`
Expected: exits 0, no diff on re-run.

- [ ] **Step 5: Evaluate the configuration**

Run: `nix eval '.#nixosConfigurations.jupiter.config.system.build.toplevel.drvPath'`
Expected: prints a `/nix/store/...-nixos-system-jupiter-*.drv` path with no evaluation errors. (This forces full module-system evaluation, catching option/type mistakes, without building a Linux derivation.)

- [ ] **Step 6: Confirm the ntfy settings evaluate as expected**

Run: `nix eval --json '.#nixosConfigurations.jupiter.config.services.ntfy-sh.settings'`
Expected JSON includes `"auth-default-access":"deny-all"`, `"listen-http":":2586"`, and `"base-url":"http://jupiter:2586"`.

- [ ] **Step 7: Commit**

```bash
git add modules/environments/ntfy/default.nix modules/environments/default.nix machines/jupiter/environments.nix
git commit -m "feat(ntfy): add self-hosted notification server module

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

### Task 2: Wire the Home Assistant rest_command

**Files:**
- Modify: `modules/environments/ntfy/default.nix` (add HA integration block)

**Interfaces:**
- Consumes: `cfg.port`, `cfg.topic`, `cfg.haIntegration.enable` (Task 1); `config.my.profiles.home-assistant.enable`; `services.home-assistant.config` (nixpkgs / repo home-assistant module).
- Produces: `services.home-assistant.config.rest_command.ntfy_send`, callable from HA automations as `service: rest_command.ntfy_send`.

- [ ] **Step 1: Add the HA integration block to the module**

The module currently has a single `config = lib.mkIf cfg.enable { ... };`. Change it to merge two conditional configs with `lib.mkMerge` so the HA wiring is gated independently. Replace the `config = lib.mkIf cfg.enable { ... };` assignment with:

```nix
  config = lib.mkMerge [
    (lib.mkIf cfg.enable {
      services.ntfy-sh = {
        enable = true;
        settings = {
          base-url = "http://${hostName}:${toString cfg.port}";
          listen-http = ":${toString cfg.port}";
          auth-file = "/var/lib/ntfy-sh/user.db";
          auth-default-access = "deny-all";
        };
      };

      networking.firewall.allowedTCPPorts = [ cfg.port ];

      my.homepage.services = [
        {
          group = "Services";
          name = "ntfy";
          description = "Push notifications";
          href = "http://${hostName}:${toString cfg.port}";
          icon = "ntfy.svg";
        }
      ];
    })

    (lib.mkIf (cfg.enable && cfg.haIntegration.enable && config.my.profiles.home-assistant.enable) {
      services.home-assistant.config.rest_command.ntfy_send = {
        url = "http://${hostName}:${toString cfg.port}/${cfg.topic}";
        method = "POST";
        payload = "{{ message }}";
        content_type = "text/plain";
        username = "homeassistant";
        password = "!secret ntfy_password";
        headers = {
          Title = "{{ title | default('Home Assistant') }}";
          Priority = "{{ priority | default('default') }}";
        };
      };
    })
  ];
```

(The first `mkIf cfg.enable` block is identical to Task 1's config body — it is repeated here because the whole `config` assignment is being replaced with the `mkMerge` form.)

- [ ] **Step 2: Format the file**

Run: `nixfmt-rfc-style modules/environments/ntfy/default.nix`
Expected: exits 0, no diff on re-run.

- [ ] **Step 3: Evaluate the configuration**

Run: `nix eval '.#nixosConfigurations.jupiter.config.system.build.toplevel.drvPath'`
Expected: prints a `.drv` path, no evaluation errors (confirms the `rest_command` merges cleanly into the HA config the home-assistant module already defines).

- [ ] **Step 4: Confirm the rest_command evaluated into HA config**

Run: `nix eval --json '.#nixosConfigurations.jupiter.config.services.home-assistant.config.rest_command.ntfy_send'`
Expected JSON includes `"url":"http://jupiter:2586/ha"`, `"username":"homeassistant"`, and `"password":"!secret ntfy_password"`.

- [ ] **Step 5: Commit**

```bash
git add modules/environments/ntfy/default.nix
git commit -m "feat(ntfy): wire Home Assistant rest_command publisher

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
```

---

## Operator steps (run by the user on jupiter — not part of the agent's task loop)

These require the host and manual credentials, so they are performed by the user after the branch is merged/deployed:

1. Deploy: `sudo nixos-rebuild switch --flake '.#jupiter'`
2. Create ntfy users:
   ```bash
   ntfy user add homeassistant            # set a password
   ntfy access homeassistant ha write-only
   ntfy user add --role=admin admin
   ```
3. Add the publisher password to Home Assistant secrets:
   ```yaml
   # /var/lib/hass/secrets.yaml
   ntfy_password: <the homeassistant user's password>
   ```
4. Restart Home Assistant, then test from an automation / Developer Tools:
   ```yaml
   service: rest_command.ntfy_send
   data:
     message: "ntfy test"
     title: "Home Assistant"
     priority: high
   ```
5. Subscribe from the ntfy app as `admin` to receive the message.

---

## Self-Review

**Spec coverage:**
- Module structure + options → Task 1. ✔
- Server config (deny-all, port, firewall) → Task 1 (steps 1, 6). ✔
- Homepage tile → Task 1. ✔
- Registration in `default.nix` + enable on jupiter → Task 1 (steps 2–3). ✔
- HA `rest_command` wiring, gated on HA profile, `!secret` password → Task 2. ✔
- Manual provisioning runbook → Operator steps section. ✔
- Verification (eval/build + nixfmt) → per-task steps. ✔
- Out-of-scope items (no seeding, no sops, no reverse proxy) → honored; no tasks added for them. ✔

**Placeholder scan:** No TBD/TODO/"handle edge cases". The one "similar to Task 1" note is accompanied by the full repeated code, per the no-placeholders rule. ✔

**Type consistency:** `cfg.port`/`cfg.topic`/`cfg.haIntegration.enable` defined in Task 1 and used identically in Task 2. `rest_command.ntfy_send` name consistent across Task 2 and operator steps. Homepage tile shape matches sibling modules. ✔