@pi-unipi/notify 0.1.9 → 0.1.10

package/README.md

@@ -1,21 +1,52 @@
 # @pi-unipi/notify
 
-Cross-platform notification extension for Pi. Sends push notifications to native OS, Gotify, Telegram, and ntfy when agent lifecycle events occur.
+Push notifications when things happen. Workflow finishes, Ralph loop completes, MCP server errors — notify sends alerts to native OS, Gotify, Telegram, or ntfy.
 
-## What it does
+Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify.
 
-- Listens to Pi lifecycle events (workflow complete, Ralph loop done, MCP errors, etc.)
-- Routes notifications to your configured platforms
-- Provides `notify_user` tool for agent-initiated notifications
-- Per-event platform configuration with sensible defaults
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:notify-settings` | Open settings overlay to configure platforms and events |
+| `/unipi:notify-set-gotify` | Configure Gotify server connection |
+| `/unipi:notify-set-tg` | Interactive Telegram bot setup |
+| `/unipi:notify-set-ntfy` | Configure ntfy topic and server |
+| `/unipi:notify-recap-model` | Set model for notification recaps |
+| `/unipi:notify-test` | Send test notification to all enabled platforms |
 
-## Installation
+## Special Triggers
 
-Part of the `@pi-unipi/unipi` meta-package. No separate install needed.
+Notify subscribes to Pi lifecycle events and routes notifications based on your config:
+
+| Event | Default | Description |
+|-------|---------|-------------|
+| `workflow_end` | On | Workflow command completes |
+| `ralph_loop_end` | On | Ralph loop completes |
+| `mcp_server_error` | On | MCP server error |
+| `agent_end` | Off | Agent finishes responding |
+| `memory_consolidated` | Off | Memory auto-saved |
+| `session_shutdown` | Off | Session ends |
+
+Notify registers with the info-screen dashboard, showing enabled platforms and last notification time. The footer subscribes to `NOTIFICATION_SENT` events to display notification stats.
+
+## Agent Tool
+
+| Tool | Description |
+|------|-------------|
+| `notify_user` | Send cross-platform notification |
+
+```
+notify_user({
+  title: "Build Failed",
+  message: "TypeScript compilation failed with 12 errors.",
+  priority: "high"
+})
+```
 
 ## Platforms
 
-### Native OS (default)
+### Native OS
 
 Desktop notifications via [node-notifier](https://github.com/mikaelbr/node-notifier):
 - **Windows:** SnoreToast (no admin required)
@@ -26,7 +57,7 @@ Zero configuration — works out of the box.
 
 ### Gotify
 
-Self-hosted push notification server. Configure in settings:
+Self-hosted push notification server:
 
 ```json
 {
@@ -41,26 +72,14 @@ Self-hosted push notification server. Configure in settings:
 
 ### Telegram
 
-Bot API notifications. Run setup command:
-
-```
-/unipi:notify-set-tg
-```
-
-This guides you through:
-1. Creating a bot via @BotFather
-2. Pasting the bot token
-3. Auto-detecting your chat ID
+Bot API notifications. Run `/unipi:notify-set-tg` for interactive setup:
+1. Create a bot via @BotFather
+2. Paste the bot token
+3. Auto-detect your chat ID
 
 ### ntfy
 
-HTTP-based pub-sub notifications via [ntfy.sh](https://ntfy.sh) or self-hosted. Run setup command:
-
-```
-/unipi:notify-set-ntfy
-```
-
-Or configure manually:
+HTTP-based pub-sub notifications via [ntfy.sh](https://ntfy.sh) or self-hosted:
 
 ```json
 {
@@ -73,54 +92,12 @@ Or configure manually:
 }
 ```
 
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `/unipi:notify-settings` | Open settings overlay to configure platforms and events |
-| `/unipi:notify-set-gotify` | Configure Gotify server connection |
-| `/unipi:notify-set-tg` | Interactive Telegram bot setup |
-| `/unipi:notify-set-ntfy` | Configure ntfy topic and server |
-| `/unipi:notify-test` | Send test notification to all enabled platforms |
-
-## Agent Tool
-
-The `notify_user` tool is available to the agent for ad-hoc notifications:
-
-```
-notify_user({
-  title: "Build Failed",
-  message: "TypeScript compilation failed with 12 errors.",
-  priority: "high"
-})
-```
-
-See the bundled `notify` skill for full parameter documentation.
-
-## Event Configuration
-
-Notifications are triggered by these events (configurable in settings):
-
-| Event | Default | Description |
-|-------|---------|-------------|
-| `workflow_end` | On | Workflow command completes |
-| `ralph_loop_end` | On | Ralph loop completes |
-| `mcp_server_error` | On | MCP server error |
-| `agent_end` | Off | Agent finishes responding |
-| `memory_consolidated` | Off | Memory auto-saved |
-| `session_shutdown` | Off | Session ends |
+## Configurables
 
-## Configuration
+Settings stored at `~/.unipi/config/notify/config.json`. Edit via `/unipi:notify-settings` or manual JSON editing.
 
-Settings stored at `~/.unipi/config/notify/config.json`. Edit via:
-- Settings overlay: `/unipi:notify-settings`
-- Manual JSON editing
-- The agent can read config via the settings module
+Per-event platform routing lets you control where each event type goes. The settings overlay shows all events with platform toggles.
 
-## Info-Screen Integration
+## License
 
-The notify module registers with the info screen showing:
-- Enabled platform count
-- Active event subscriptions
-- Last notification timestamp
-- Total notifications sent this session
+MIT

package/ntfy-config.ts

@@ -0,0 +1,178 @@
+/**
+ * @pi-unipi/notify — Project-level ntfy configuration
+ *
+ * Loads, saves, and resolves ntfy config from dedicated ntfy.json files
+ * at global (~/.unipi/config/notify/ntfy.json) and project
+ * (<cwd>/.unipi/config/notify/ntfy.json) scope.
+ *
+ * Resolution: project → global → defaults.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import type { NtfyConfig } from "./types.js";
+
+/** Default ntfy configuration */
+const DEFAULT_NTFY_CONFIG: NtfyConfig = {
+  enabled: false,
+  serverUrl: "https://ntfy.sh",
+  priority: 3,
+};
+
+/** Global ntfy.json path: ~/.unipi/config/notify/ntfy.json */
+function getGlobalNtfyPath(): string {
+  return join(homedir(), ".unipi", "config", "notify", "ntfy.json");
+}
+
+/** Project ntfy.json path: <cwd>/.unipi/config/notify/ntfy.json */
+function getProjectNtfyPath(cwd: string): string {
+  return join(cwd, ".unipi", "config", "notify", "ntfy.json");
+}
+
+/**
+ * Read and parse a ntfy.json file.
+ * Returns null if file doesn't exist (ENOENT).
+ * Returns null and logs warning on parse error.
+ */
+function readNtfyJson(filePath: string): NtfyConfig | null {
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<NtfyConfig>;
+    return { ...DEFAULT_NTFY_CONFIG, ...parsed };
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    console.warn(`[notify] Failed to parse ${filePath}: ${(err as Error).message}. Falling back.`);
+    return null;
+  }
+}
+
+/**
+ * Resolve ntfy config with project → global → defaults priority.
+ *
+ * 1. If project ntfy.json exists → use it
+ * 2. If only global ntfy.json exists → use it
+ * 3. If neither exists → return defaults (ntfy disabled)
+ *
+ * Runs legacy migration once if global ntfy.json is missing.
+ */
+export function loadNtfyConfig(cwd: string): NtfyConfig {
+  // Attempt migration from legacy config.json if global ntfy.json doesn't exist
+  migrateFromLegacyConfig();
+
+  // Try project-level first
+  const projectConfig = readNtfyJson(getProjectNtfyPath(cwd));
+  if (projectConfig !== null) {
+    return projectConfig;
+  }
+
+  // Try global level
+  const globalConfig = readNtfyJson(getGlobalNtfyPath());
+  if (globalConfig !== null) {
+    return globalConfig;
+  }
+
+  // Neither exists — return defaults
+  return { ...DEFAULT_NTFY_CONFIG };
+}
+
+/**
+ * Save ntfy config to the chosen scope.
+ * Creates parent directory if needed.
+ */
+export function saveNtfyConfig(
+  scope: "project" | "global",
+  cwd: string,
+  config: NtfyConfig
+): void {
+  const filePath =
+    scope === "project" ? getProjectNtfyPath(cwd) : getGlobalNtfyPath();
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Detect which scope is currently active for ntfy config.
+ *
+ * - "project" if project ntfy.json exists
+ * - "global" if global ntfy.json exists (and no project override)
+ * - "none" if neither exists
+ */
+export function getNtfyConfigScope(
+  cwd: string
+): "project" | "global" | "none" {
+  if (existsSync(getProjectNtfyPath(cwd))) {
+    return "project";
+  }
+  if (existsSync(getGlobalNtfyPath())) {
+    return "global";
+  }
+  return "none";
+}
+
+/**
+ * One-time migration from legacy config.json ntfy section to ntfy.json.
+ *
+ * Trigger conditions:
+ * - Global ntfy.json does NOT exist
+ * - config.json has non-default ntfy settings (enabled or topic/serverUrl set)
+ *
+ * After migration, config.json ntfy section is left untouched.
+ * Future reads use ntfy.json exclusively.
+ */
+export function migrateFromLegacyConfig(): void {
+  const globalNtfyPath = getGlobalNtfyPath();
+
+  // Only migrate if global ntfy.json doesn't exist yet
+  if (existsSync(globalNtfyPath)) {
+    return;
+  }
+
+  // Try to read legacy config.json
+  const legacyConfigPath = join(
+    homedir(),
+    ".unipi",
+    "config",
+    "notify",
+    "config.json"
+  );
+
+  try {
+    if (!existsSync(legacyConfigPath)) return;
+    const raw = readFileSync(legacyConfigPath, "utf-8");
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const ntfySection = parsed.ntfy as Partial<NtfyConfig> | undefined;
+
+    if (!ntfySection) return;
+
+    // Only migrate if there's something meaningful to migrate
+    const hasCustomConfig =
+      ntfySection.enabled === true ||
+      (ntfySection.serverUrl && ntfySection.serverUrl !== "https://ntfy.sh") ||
+      ntfySection.topic;
+
+    if (!hasCustomConfig) return;
+
+    // Write ntfy.json from legacy config
+    const migratedConfig: NtfyConfig = {
+      enabled: ntfySection.enabled ?? false,
+      serverUrl: ntfySection.serverUrl ?? "https://ntfy.sh",
+      topic: ntfySection.topic,
+      token: ntfySection.token,
+      priority: ntfySection.priority ?? 3,
+    };
+
+    const dir = dirname(globalNtfyPath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      globalNtfyPath,
+      JSON.stringify(migratedConfig, null, 2) + "\n",
+      "utf-8"
+    );
+  } catch {
+    // Migration failure is non-fatal — silently continue
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
     "commands.ts",
     "settings.ts",
     "events.ts",
+    "ntfy-config.ts",
     "summarize.ts",
     "types.ts",
     "platforms/*",