@checkstack/catalog-common 1.5.3 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,291 @@
 # @checkstack/catalog-common
 
+## 2.0.1
+
+### Patch Changes
+
+- 50e5f5f: Runtime plugin system: install + uninstall plugins from npm, GitHub releases
+  (including private GitHub Enterprise instances), or tarball uploads at
+  runtime, with multi-package bundles, dependency-derived compatibility checks,
+  multi-instance coordination via a Postgres artifact store, and
+  single-coordinator destructive cleanup.
+
+  Highlights:
+
+  - New `PluginSource` discriminated union and `PluginInstaller` /
+    `PluginInstallerRegistry` interfaces in `@checkstack/backend-api`. The
+    GitHub variant accepts an optional `apiBaseUrl` so deployments backed by
+    GitHub Enterprise can install from `https://ghe.example.com/api/v3`
+    instead of `api.github.com`.
+  - New `installPackageMetadataSchema` (Zod) in `@checkstack/common` validates
+    every plugin's `package.json` at install time. Required fields: `name`,
+    `version`, `description`, `author`, `license`, `checkstack.type`,
+    `checkstack.pluginId`. Optional: `checkstack.bundle`,
+    `checkstack.usageInstructions`, `checkstack.allowInstallScripts`.
+  - New `pluginManagerContract` in `@checkstack/pluginmanager-common` with
+    `list`, `previewInstall`, `install`, `previewUninstall`, `uninstall`, and
+    `events` procedures.
+  - New `@checkstack/pluginmanager-frontend` admin UI: installed-plugins list
+    with per-row uninstall (typed-confirmation modal, schema/configs/cascade
+    toggles), install page with NPM / Tarball Upload / GitHub Release tabs
+    (Catalog tab disabled — coming soon), and an events page surfacing the
+    install/uninstall audit log.
+  - New `bunx @checkstack/scripts plugin-pack` CLI for plugin authors —
+    per-package mode produces an npm-shaped tarball; `--bundle` mode produces
+    an outer tarball containing every sibling declared in
+    `package.json#checkstack.bundle`. Published to npm so external authors
+    can `bunx` it directly without a workspace checkout.
+  - Compatibility derived from `package.json#dependencies` ranges
+    (`semver.satisfies` against the platform's loaded `@checkstack/*`
+    versions) — no separate `compatibility` field.
+  - Multi-instance: originator persists artifacts + `plugins` rows + broadcasts
+    install/uninstall; receiving instances do in-process register/unregister
+    only. Destructive ops (drop schema, delete plugin_configs, delete
+    artifacts, delete `plugins` rows) run exactly once on the originator.
+  - Fresh-instance bootstrap: `loadPlugins()` hydrates any
+    `is_uninstallable=true` plugin missing from `node_modules` from the
+    artifact store before normal Phase 1 register.
+  - New schema: `plugin_artifacts` (tarball storage), `plugin_install_events`
+    (audit/error log). `plugins` extended with `version`, `metadata`,
+    `source`, `bundle_id`, `is_primary`. Local plugin sync now writes
+    `version` from each plugin's `package.json` so the admin UI shows real
+    versions instead of `—`.
+  - Tarball-upload endpoint (`POST /api/pluginmanager/upload-tarball`) for
+    the install UI; access-gated by `pluginmanager.plugin.manage`.
+  - Plugin Manager menu link added to the user menu (main grid, alongside
+    Profile / Notification Settings / etc.).
+
+  Cross-cutting changes:
+
+  - Backend request/response logging now flows through `rootLogger` (winston)
+    instead of `hono/logger`. 5xx responses include the response body inline
+    so swallowed early-return errors are visible in the log.
+  - The `/api/:pluginId/*` dispatcher now logs which core service is missing
+    or which `pluginId` had no metadata when it 500s.
+  - New `registerCorePluginMetadata` on `PluginManager` for core routers
+    (like the plugin manager itself) that need their metadata visible to the
+    RPC dispatcher without going through the full plugin lifecycle.
+  - ESLint: `unicorn/no-null` is now disabled globally. Drizzle distinguishes
+    between `null` (writes a real SQL NULL) and `undefined` (skip the column
+    on insert), so treating them as interchangeable produced latent bugs at
+    the persistence boundary. The bulk of the patch-bumped packages above
+    reflect lint-fix touches that landed when this rule was relaxed.
+  - Workspace-wide license normalization to `Elastic-2.0` (matches
+    `LICENSE.md`). Every `package.json` in the workspace now declares the
+    same SPDX identifier; the patch bumps capture this.
+
+  Plugin packages (every `plugins/*`): added a `pack` npm script
+  (`bunx @checkstack/scripts plugin-pack`), mirrored each plugin's
+  `pluginId` from `plugin-metadata.ts` into `package.json#checkstack.pluginId`
+  so install-time validation passes, stubbed any missing required metadata
+  fields (`description`, `author`, `license`), and added
+  `checkstack.bundle` to multi-package plugin primaries (telegram, rcon, ssh,
+  jira, queue-bullmq, queue-memory, cache-memory).
+
+  Breaking changes:
+
+  - The legacy single-method `PluginInstaller` interface (`install(packageName)`)
+    is removed. Callers must use `coreServices.pluginInstallerRegistry`.
+  - The old `pluginAdminContract` and `createPluginAdminRouter` are removed.
+    Replaced by `pluginManagerContract` in `@checkstack/pluginmanager-common`
+    and `createPluginManagerRouter` in `core/backend`.
+  - `@checkstack/test-utils-backend` no longer exports
+    `createMockPluginInstaller` / `MockPluginInstaller` (the legacy interface
+    it shimmed is gone).
+
+  Note: bumps are limited to `minor` (for packages with new public API
+  surface) and `patch` (for downstream consumers, license normalization,
+  and lint fixes). No `major` bumps despite the `PluginInstaller` removal —
+  the legacy interface had no third-party consumers in the wild before this
+  runtime plugin system landed, and the contract surface is the same shape
+  modulo the rename.
+
+- Updated dependencies [50e5f5f]
+  - @checkstack/auth-common@0.6.5
+  - @checkstack/common@0.8.0
+  - @checkstack/frontend-api@0.4.2
+  - @checkstack/notification-common@1.0.1
+
+## 2.0.0
+
+### Major Changes
+
+- 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).
+
+### Minor Changes
+
+- 32d52c6: Bulk notifications affecting multiple systems and collapse lifecycle events into a single card.
+
+  Notifications now carry an optional `subjects` array (the entities they affect) and an optional `collapseKey` (so related notifications collapse into one row per recipient). Incidents, maintenances, anomalies, healthchecks, and dependency-impact events route through these new fields, so an incident affecting three systems produces one in-app notification + one external send per subscriber instead of three. Lifecycle updates for the same entity (created → updated → resolved) also collapse, with an expandable "+N updates" timeline.
+
+  Subject kinds are namespaced as `<pluginId>.<localKind>` and built via type-safe helpers exported from each domain's common package (`createSystemSubject`, `incidentCollapseKey`, etc.). The frontend kind registry (`registerSubjectKind`) lets plugins bind icon + label for their kinds; unknown kinds fall back to a generic chip.
+
+  All notification strategies (SMTP, Slack, Discord, Teams, Telegram, Pushover, Gotify, Webex, Backstage) render the affected subjects natively in their format (HTML cards, Slack blocks, Discord embed fields, adaptive cards, markdown lists, etc.).
+
+- 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.
+
+### Patch Changes
+
+- 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/frontend-api@0.4.1
+  - @checkstack/auth-common@0.6.4
+
 ## 1.5.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@checkstack/catalog-common",
-  "version": "1.5.3",
+  "version": "2.0.1",
+  "license": "Elastic-2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -9,18 +10,19 @@
   },
   "dependencies": {
     "@checkstack/common": "0.7.0",
-    "@checkstack/auth-common": "0.6.3",
-    "@checkstack/frontend-api": "0.3.11",
+    "@checkstack/auth-common": "0.6.4",
+    "@checkstack/frontend-api": "0.4.1",
+    "@checkstack/notification-common": "1.0.0",
     "@orpc/contract": "^1.13.14",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
-    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/tsconfig": "0.0.6",
     "@checkstack/scripts": "0.1.2"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
     "lint:code": "eslint . --max-warnings 0"
   },

package/src/index.ts

@@ -3,4 +3,5 @@ export * from "./rpc-contract";
 export * from "./types";
 export * from "./slots";
 export * from "./plugin-metadata";
+export * from "./notifications";
 export { catalogRoutes } from "./routes";

package/src/notifications.ts

@@ -0,0 +1,71 @@
+import {
+  createSubjectKindBuilder,
+  defineNotificationTarget,
+} from "@checkstack/notification-common";
+import { pluginMetadata } from "./plugin-metadata";
+
+/**
+ * Builders for the catalog plugin's notification subject kinds. Use these
+ * instead of constructing `NotificationSubject` literals so the kind
+ * namespace stays in sync with the plugin id.
+ */
+export const createSystemSubject = createSubjectKindBuilder(
+  pluginMetadata,
+  "system",
+);
+
+export const createGroupSubject = createSubjectKindBuilder(
+  pluginMetadata,
+  "group",
+);
+
+// ─── Notification targets ────────────────────────────────────────────────────
+// Catalog owns the platform's "system" and "group" target types. Emitting
+// plugins (anomaly, incident, maintenance, healthcheck, ...) reference
+// these objects directly when defining their subscription specs — no
+// strings, no per-plugin lifecycle code.
+
+export interface CatalogSystemResource {
+  systemId: string;
+  systemName: string;
+}
+
+export interface CatalogGroupResource {
+  groupId: string;
+  groupName: string;
+}
+
+/**
+ * The "system" target type. Resources are the entries of catalog's
+ * `systems` table; the catalog backend pushes them to notification-
+ * backend whenever a system is created, renamed, or deleted, and
+ * declares each system's parent catalog groups.
+ *
+ * `legacy.legacyGroupIdTemplate` covers users who were already
+ * subscribed to the pre-pattern `catalog.system.<id>` group — the
+ * notification backend seeds new spec groups from those subscribers
+ * exactly once per (spec × resource) pair.
+ */
+export const catalogSystemTarget = defineNotificationTarget<CatalogSystemResource>({
+  pluginMetadata,
+  localId: "system",
+  resourceKind: "system",
+  keyOf: ({ systemId }) => systemId,
+  labelOf: ({ systemName }) => systemName,
+  parents: { targetTypeId: `${pluginMetadata.pluginId}.group` },
+  legacy: { legacyGroupIdTemplate: "catalog.system.{resourceKey}" },
+});
+
+/**
+ * The "group" target type. Catalog groups don't currently have parent
+ * resources; emitting plugins targeting groups deliver only to direct
+ * subscribers of the group.
+ */
+export const catalogGroupTarget = defineNotificationTarget<CatalogGroupResource>({
+  pluginMetadata,
+  localId: "group",
+  resourceKind: "group",
+  keyOf: ({ groupId }) => groupId,
+  labelOf: ({ groupName }) => groupName,
+  legacy: { legacyGroupIdTemplate: "catalog.group.{resourceKey}" },
+});

package/src/rpc-contract.ts

@@ -83,6 +83,21 @@ export const catalogContract = {
     access: [catalogAccess.group.read],
   }).output(z.array(GroupSchema)),
 
+  /**
+   * Returns the catalog groups a system belongs to. Used by host plugins
+   * (catalog) and emitting plugins (e.g. anomaly) to walk parent
+   * subscriptions and surface inheritance hints. Server-side join — no
+   * client-side filtering of `getGroups()` needed.
+   */
+  getSystemGroups: proc({
+    operationType: "query",
+    userType: "public",
+    access: [catalogAccess.system.read],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({ systemId: z.string() }))
+    .output(z.array(GroupSchema)),
+
   // ==========================================================================
   // SYSTEM MANAGEMENT (userType: "authenticated" with manage access)
   // ==========================================================================
@@ -229,44 +244,6 @@ export const catalogContract = {
   // SERVICE INTERFACE (userType: "service" - backend-to-backend only)
   // ==========================================================================
 
-  /**
-   * Notify all users subscribed to a system (and optionally its groups).
-   * This is used by other plugins (e.g., maintenance) to send notifications
-   * to system subscribers without needing direct access to the notification service.
-   *
-   * Deduplication: If includeGroupSubscribers is true, subscribers are
-   * deduplicated so users subscribed to both the system AND its groups
-   * receive only one notification.
-   */
-  notifySystemSubscribers: proc({
-    operationType: "mutation",
-    userType: "service",
-    access: [], // Service-to-service, no access rules needed
-  })
-    .input(
-      z.object({
-        systemId: z
-          .string()
-          .describe("The system ID to notify subscribers for"),
-        title: z.string().describe("Notification title"),
-        body: z.string().describe("Notification body (supports markdown)"),
-        importance: z.enum(["info", "warning", "critical"]).optional(),
-        action: z
-          .object({
-            label: z.string(),
-            url: z.string(),
-          })
-          .optional(),
-        includeGroupSubscribers: z
-          .boolean()
-          .optional()
-          .describe(
-            "If true, also notify subscribers of groups that contain this system",
-          ),
-      }),
-    )
-    .output(z.object({ notifiedCount: z.number() })),
-
   /**
    * Get the catalog group IDs that contain a specific system.
    * Returns raw group IDs (not namespaced with notification prefix).

package/tsconfig.json

@@ -2,5 +2,19 @@
   "extends": "@checkstack/tsconfig/common.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../auth-common"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../frontend-api"
+    },
+    {
+      "path": "../notification-common"
+    }
   ]
-}
+}