@checkstack/maintenance-frontend 0.5.7 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,221 @@
 # @checkstack/maintenance-frontend
 
+## 0.6.0
+
+### Minor Changes
+
+- 32d52c6: feat: unified notification-subscription manager dialog driven by spec registry
+
+  Replaces the bell-toggle UX (which only managed a single legacy
+  catalog group) with a modal that lists every notification type
+  registered against a target — system or group — and exposes both
+  per-type toggles and a bulk "Subscribe to all / Unsubscribe from all"
+  action. Both surfaces (system detail page header bell, dashboard group
+  header bell) now open the same `NotificationSubscriptionsManager`
+  component.
+
+  **Key change vs. the prior slot-based approach**: rows are now driven
+  by `notificationClient.listSubscriptionSpecs` — the backend's spec
+  registry is the single source of truth. Previously, a row only
+  appeared if a frontend plugin had remembered to register a
+  `createNotificationSubscriptionExtension`; this caused silent drift
+  (healthcheck and dependency registered backend specs without frontend
+  extensions, so the dialog counted them but never rendered rows). Now,
+  every spec the platform knows about renders a row using the spec's
+  `display` metadata (title, description, iconName resolved via
+  `DynamicIcon`).
+
+  **Sub-controls registry** (`@checkstack/notification-frontend`):
+  plugins that want sub-granularity (anomaly's per-field mute list,
+  future severity / channel filters) call
+  `registerSubscriptionSubControls(spec, Component)` at module load —
+  the manager looks the component up by `specId` when expanding a row.
+
+  **Removed (no compat)**:
+
+  - `createNotificationSubscriptionExtension` (replaced by the
+    spec-driven manager + the SubControls registry)
+  - `target.slot` field on `NotificationTarget` and the
+    `NotificationTargetInput.slot` parameter on
+    `defineNotificationTarget`
+  - `SystemNotificationSubscriptionsSlot` and
+    `GroupNotificationSubscriptionsSlot` from `@checkstack/catalog-common`
+  - `SystemNotificationsCard` from the system detail page's main column
+  - `SubscribeButton` wiring on dashboard group cards and the system
+    detail page header
+
+  **Migrated frontends**: anomaly (now registers `AnomalyFieldMuteList`
+  via the SubControls registry), incident, maintenance — all dropped
+  their `createNotificationSubscriptionExtension` calls. healthcheck and
+  dependency now show up automatically via the spec registry — no
+  frontend changes needed for them to render.
+
+  The trigger button reflects aggregate state — filled bell when at
+  least one spec is subscribed for the resource, ghost bell when none.
+
+- 32d52c6: feat: notification target pattern + per-spec subscriptions
+
+  Replaces the all-or-nothing catalog system/group notification model with a
+  platform-level target pattern. Each notification-emitting plugin declares
+  _subscription specs_ against typed _target_ objects exported from the
+  target's owning plugin (catalog ships `catalogSystemTarget` and
+  `catalogGroupTarget`). Notification-backend handles every per-resource
+  group lifecycle, parent-edge inheritance, and legacy-subscription seeding
+  — plugins never author groupId helpers, lifecycle hooks, or migration
+  code again.
+
+  **Plugin-author surface area is now ~12 lines per emitter:**
+
+  ```ts
+  // <plugin>-common
+  const { defineSubscription } = createSubscriptionFactory(pluginMetadata);
+  export const fooSystemSubscription = defineSubscription({
+    localId: "system",
+    target: catalogSystemTarget,
+    display: { title: "Foo Alerts", description: "...", iconName: "Bell" },
+  });
+
+  // <plugin>-backend register()
+  env.registerSubscriptionSpecs([fooSystemSubscription]);
+  //   ^ feeds the plugin loader's dependency sorter — each spec's
+  //     target.ownerPlugin becomes an implicit init-order dep, so this
+  //     plugin automatically waits for catalog (the target owner) to
+  //     finish init + afterPluginsReady before its own runs.
+
+  // <plugin>-backend afterPluginsReady
+  await notificationClient.registerSubscriptionSpec(
+    specToRegistration(fooSystemSubscription)
+  );
+  // dispatch
+  await notificationClient.notifyForSubscription({
+    specId: fooSystemSubscription.specId,
+    resourceKeys: [systemId],
+    title,
+    body,
+    importance,
+    action,
+    collapseKey,
+    subjects,
+  });
+
+  // <plugin>-frontend
+  createNotificationSubscriptionExtension({ spec: fooSystemSubscription });
+  ```
+
+  **Migrated plugins**: anomaly, incident, maintenance, healthcheck,
+  dependency. Each lost its bespoke `notification-groups.ts`,
+  `bootstrap*NotificationGroups`, `ensure*Group`, and inheritance walk —
+  all of that is now centralized in notification-backend's
+  `subscription-engine`.
+
+  **Plugin loader change** (`@checkstack/backend-api`,
+  `@checkstack/backend`): the register-time API gains
+  `env.registerSubscriptionSpecs([...specs])`. The dependency sorter
+  walks `spec.target.ownerPlugin` for every declared spec and adds the
+  target owner as an init-order dependency of the emitting plugin. This
+  guarantees that catalog (the owner of the platform's `system` and
+  `group` targets) completes init + afterPluginsReady before any
+  emitting plugin tries to register its specs against the notification
+  service — no string-prefix heuristics, no manual `dependsOnPlugins`
+  list, no stub rows. Plugins that fail to declare their specs at
+  register time get a clear `Target type X is not registered. Did the
+emitting plugin declare this spec via env.registerSubscriptionSpecs?`
+  error from the dispatcher.
+
+  **Removed** (no backwards compat):
+
+  - `catalogClient.notifySystemSubscribers` and
+    `catalogClient.notifyManySystemSubscribers`
+  - `notificationClient.notifyUsers` and `notificationClient.notifyGroups`
+    as direct dispatch primitives — replaced by spec-bound
+    `notifyForSubscription`
+  - catalog's `bootstrapNotificationGroups` (replaced by
+    `bootstrapNotificationTargets`)
+
+  **Enforcement**: the dispatcher rejects calls referencing unregistered
+  specIds, specs owned by other plugins, or resourceKeys that haven't been
+  pushed via `upsertNotificationResource`. Display metadata for any
+  groupId is recoverable via the spec registry, so audit lists render
+  correct labels even when an emitter's frontend isn't loaded.
+
+  **Per-field anomaly mute** keeps working — it now lives inside the
+  generic SubscriptionRow's optional `SubControls` panel
+  (`AnomalyFieldMuteList`), exposed through the catalog system detail
+  page's notifications card.
+
+  The catalog system detail page renders a "Notifications" card hosting
+  `SystemNotificationSubscriptionsSlot`. The matching group surface is
+  not yet rendered — group-level subscriptions are wired end-to-end on
+  the backend; a follow-up will add the host UI.
+
+  **Migration of existing subscribers**: target types declare a
+  `legacyGroupIdTemplate`; on first registration of each spec,
+  notification-backend reads subscribers from the legacy
+  `catalog.system.<id>` / `catalog.group.<id>` groups and seeds the new
+  spec groups exactly once per (spec × resource) pair, tracked in
+  `subscription_migrations`. Anomaly stays opt-in (its target also
+  declares the template, but the user-explicit nature of the original
+  opt-in flow means the seeding produces the same set of subscribers
+  they already had).
+
+### Patch Changes
+
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+  - @checkstack/notification-common@1.0.0
+  - @checkstack/notification-frontend@0.3.0
+  - @checkstack/catalog-common@2.0.0
+  - @checkstack/maintenance-common@1.0.0
+  - @checkstack/dashboard-frontend@0.6.0
+  - @checkstack/frontend-api@0.4.1
+  - @checkstack/auth-frontend@0.5.32
+  - @checkstack/ui@1.7.0
+
+## 0.5.8
+
+### Patch Changes
+
+- 208ad71: Centralize realtime cache invalidation: signals now carry their owning `pluginId` end-to-end, and a single `SignalAutoInvalidator` mounted near the React Query client invalidates `[[pluginId]]` for every incoming signal automatically.
+
+  **Breaking change to `createSignal`** (`@checkstack/signal-common`): the factory now takes a single object argument with `pluginMetadata`, `event`, and `payloadSchema`. The signal id is constructed as `${pluginMetadata.pluginId}.${event}` and the resulting `Signal` carries a `pluginId` field. The `SignalMessage` wire envelope and `ServerToClientMessage` `signal` variant gained a `pluginId` field so the frontend can route invalidations without parsing the id.
+
+  ```ts
+  // Before
+  export const ANOMALY_STATE_CHANGED = createSignal(
+    "anomaly.state_changed",
+    z.object({ ... }),
+  );
+
+  // After
+  export const ANOMALY_STATE_CHANGED = createSignal({
+    pluginMetadata,
+    event: "state_changed",
+    payloadSchema: z.object({ ... }),
+  });
+  ```
+
+  **New plugin field**: `FrontendPlugin.foreignSignals?: Signal<unknown>[]` lets a plugin opt its `[[pluginId]]` cache into invalidation when another plugin's signal fires (e.g. `dependency-frontend` declares `[SYSTEM_STATUS_CHANGED]` because dependency payloads embed system status). Same-plugin signals must NOT be listed — they are always auto-invalidated.
+
+  **Removed boilerplate**: per-component `useSignal(X, () => refetch())` and `useSignal(X, () => queryClient.invalidateQueries(...))` calls have been removed across `incident-frontend`, `maintenance-frontend`, `healthcheck-frontend`, `slo-frontend`, `dependency-frontend`, `satellite-frontend`, `announcement-frontend`, `notification-frontend`, and `dashboard-frontend`. The `NotificationBell` unread count is now derived directly from the `getUnreadCount` query (auto-invalidated) instead of a local state mirror.
+
+  **User-visible bug fix**: the system detail page anomaly widget (`SystemAnomalyWidget`) now updates in real-time when anomalies change, with no per-widget signal subscription required. The dashboard status page also stays fresh on `ANOMALY_STATE_CHANGED`, `ANOMALY_BASELINE_UPDATED`, and `ANOMALY_TREND_DETECTED`.
+
+  UI-state consumers that legitimately need a `useSignal` (the dashboard activity terminal, the queue lag alert, and the rolling-preset date refresh in `useHealthCheckData`) keep their handlers; the auto-invalidator runs alongside them.
+
+- Updated dependencies [208ad71]
+  - @checkstack/signal-frontend@0.1.0
+  - @checkstack/frontend-api@0.4.0
+  - @checkstack/maintenance-common@0.5.0
+  - @checkstack/dashboard-frontend@0.5.1
+  - @checkstack/auth-frontend@0.5.31
+  - @checkstack/catalog-common@1.5.3
+  - @checkstack/ui@1.6.1
+
 ## 0.5.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-frontend",
-  "version": "0.5.7",
+  "version": "0.6.0",
   "type": "module",
   "main": "src/index.tsx",
   "checkstack": {
@@ -12,14 +12,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/auth-frontend": "0.5.29",
-    "@checkstack/catalog-common": "1.5.1",
-    "@checkstack/common": "0.6.5",
-    "@checkstack/dashboard-frontend": "0.4.6",
-    "@checkstack/frontend-api": "0.3.10",
-    "@checkstack/maintenance-common": "0.4.10",
-    "@checkstack/signal-frontend": "0.0.15",
-    "@checkstack/ui": "1.5.1",
+    "@checkstack/auth-frontend": "0.5.31",
+    "@checkstack/catalog-common": "1.5.3",
+    "@checkstack/common": "0.7.0",
+    "@checkstack/dashboard-frontend": "0.5.1",
+    "@checkstack/frontend-api": "0.4.0",
+    "@checkstack/maintenance-common": "0.5.0",
+    "@checkstack/notification-common": "0.3.0",
+    "@checkstack/notification-frontend": "0.2.36",
+    "@checkstack/signal-frontend": "0.1.0",
+    "@checkstack/ui": "1.6.1",
     "date-fns": "^4.1.0",
     "lucide-react": "^0.344.0",
     "react": "^18.2.0",

package/src/components/SystemMaintenanceBadge.tsx

@@ -1,12 +1,8 @@
 import React from "react";
 import { usePluginClient, type SlotContext } from "@checkstack/frontend-api";
-import { useSignal } from "@checkstack/signal-frontend";
 import { SystemStateBadgesSlot } from "@checkstack/catalog-common";
 import { MaintenanceApi } from "../api";
-import {
-  MAINTENANCE_UPDATED,
-  type MaintenanceWithSystems,
-} from "@checkstack/maintenance-common";
+import { type MaintenanceWithSystems } from "@checkstack/maintenance-common";
 import { Badge } from "@checkstack/ui";
 import { useSystemBadgeDataOptional } from "@checkstack/dashboard-frontend";
 
@@ -26,20 +22,19 @@ function hasActiveMaintenance(maintenances: MaintenanceWithSystems[]): boolean {
  * When rendered within SystemBadgeDataProvider, uses bulk-fetched data.
  * Otherwise, falls back to individual fetch.
  *
- * Listens for realtime updates via signals.
+ * Realtime updates arrive via the SignalAutoInvalidator (auto-invalidates
+ * `[["maintenance"]]` queries when MAINTENANCE_UPDATED fires).
  */
 export const SystemMaintenanceBadge: React.FC<Props> = ({ system }) => {
   const maintenanceClient = usePluginClient(MaintenanceApi);
   const badgeData = useSystemBadgeDataOptional();
 
-  // Try to get data from provider first
   const providerData = badgeData?.getSystemBadgeData(system?.id ?? "");
   const providerHasActive = providerData
     ? hasActiveMaintenance(providerData.maintenances)
     : false;
 
-  // Query for maintenances if not using provider
-  const { data: maintenances, refetch } =
+  const { data: maintenances } =
     maintenanceClient.getMaintenancesForSystem.useQuery(
       { systemId: system?.id ?? "" },
       { enabled: !badgeData && !!system?.id }
@@ -49,14 +44,6 @@ export const SystemMaintenanceBadge: React.FC<Props> = ({ system }) => {
     ? hasActiveMaintenance(maintenances)
     : false;
 
-  // Listen for realtime maintenance updates (only in fallback mode)
-  useSignal(MAINTENANCE_UPDATED, ({ systemIds }) => {
-    if (!badgeData && system?.id && systemIds.includes(system.id)) {
-      void refetch();
-    }
-  });
-
-  // Use provider data if available, otherwise use local state
   const hasActive = badgeData ? providerHasActive : localHasActive;
 
   if (!hasActive) return;

package/src/components/SystemMaintenancePanel.tsx

@@ -1,14 +1,10 @@
 import React from "react";
 import { Link } from "react-router-dom";
 import { usePluginClient, type SlotContext } from "@checkstack/frontend-api";
-import { useSignal } from "@checkstack/signal-frontend";
 import { resolveRoute } from "@checkstack/common";
 import { SystemDetailsSlot } from "@checkstack/catalog-common";
 import { MaintenanceApi } from "../api";
-import {
-  maintenanceRoutes,
-  MAINTENANCE_UPDATED,
-} from "@checkstack/maintenance-common";
+import { maintenanceRoutes } from "@checkstack/maintenance-common";
 import { LoadingSpinner, Button } from "@checkstack/ui";
 import { Wrench, History } from "lucide-react";
 
@@ -21,22 +17,12 @@ type Props = SlotContext<typeof SystemDetailsSlot>;
 export const SystemMaintenancePanel: React.FC<Props> = ({ system }) => {
   const maintenanceClient = usePluginClient(MaintenanceApi);
 
-  // Fetch maintenances with useQuery
-  const {
-    data: maintenances = [],
-    isLoading: loading,
-    refetch,
-  } = maintenanceClient.getMaintenancesForSystem.useQuery(
-    { systemId: system?.id ?? "" },
-    { enabled: !!system?.id }
-  );
-
-  // Listen for realtime maintenance updates
-  useSignal(MAINTENANCE_UPDATED, ({ systemIds }) => {
-    if (system?.id && systemIds.includes(system.id)) {
-      void refetch();
-    }
-  });
+  // Fetch maintenances with useQuery — kept fresh via SignalAutoInvalidator.
+  const { data: maintenances = [], isLoading: loading } =
+    maintenanceClient.getMaintenancesForSystem.useQuery(
+      { systemId: system?.id ?? "" },
+      { enabled: !!system?.id }
+    );
 
   if (loading) {
     return (