@checkstack/incident-common 1.7.2 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @checkstack/incident-common
 
+## 1.8.0
+
+### Minor Changes
+
+- 9d30324: Incidents can now optionally override the health status of their affected
+  systems. When creating or editing an incident you can pick "Override system
+  health" (Degraded or Unhealthy); while the incident is active (not resolved)
+  that status is folded into every affected system's derived health via
+  worst-wins, so it shows on every health surface (status pages, dashboards,
+  dependency map, catalog badges). A health check reporting a worse status still
+  wins, and the override lifts automatically when the incident resolves. This
+  covers components that no automated check can monitor (e.g. a running app whose
+  licenses were revoked so it won't open).
+
+  The override is a deliberate operator choice, independent of the incident's
+  severity. A new service-typed incident RPC `getActiveHealthOverrides` exposes
+  active overrides per system, which `@checkstack/healthcheck-backend` reads and
+  folds into `getSystemHealthStatus`. The system-health response gains an optional
+  `override` field naming the contributing incident so UIs can explain why a
+  system reads unhealthy when its checks look fine. The system health badge uses
+  it to show, on hover, when a status was forced by an incident.
+
+  The dashboard "problem system" signal attributes an override-forced status to
+  the incident ("Forced by incident: <title>") instead of misreporting
+  "0 of N checks failing", while a genuinely worse health check still drives the
+  signal and its detail. Public status pages reflect the forced status but never
+  carry the incident title (the widget DTOs project only the status), so an
+  override cannot leak the name of a hidden incident.
+
+  Behavior change: a system's derived health now reflects active incident
+  overrides in addition to its health checks. Adds a forward-only migration for
+  the new nullable `incidents.health_override` column.
+
+  Thanks to [@stuajnht](https://github.com/stuajnht) for the valuable feedback
+  that shaped this release.
+
 ## 1.7.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-common",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "license": "Elastic-2.0",
   "type": "module",
   "sideEffects": [

package/src/index.ts

@@ -6,11 +6,15 @@ export {
 export {
   incidentContract,
   IncidentApi,
+  SystemHealthOverrideSchema,
+  type SystemHealthOverride,
   type IncidentContract,
 } from "./rpc-contract";
 export {
   IncidentStatusEnum,
   IncidentSeverityEnum,
+  IncidentHealthOverrideEnum,
+  type IncidentHealthOverride,
   IncidentSchema,
   IncidentWithSystemsSchema,
   IncidentUpdateSchema,

package/src/rpc-contract.ts

@@ -12,11 +12,24 @@ import {
   UpdateIncidentInputSchema,
   AddIncidentUpdateInputSchema,
   IncidentStatusEnum,
+  IncidentHealthOverrideEnum,
   BulkIncidentActionResultSchema,
   BulkIncidentIdsInputSchema,
   BulkResolveIncidentsInputSchema,
 } from "./schemas";
 
+/**
+ * One active incident forcing a health status onto a system. Returned by
+ * `getActiveHealthOverrides` and consumed by `@checkstack/healthcheck-backend`
+ * to fold incident overrides into a system's derived health (worst-wins).
+ */
+export const SystemHealthOverrideSchema = z.object({
+  status: IncidentHealthOverrideEnum,
+  incidentId: z.string(),
+  incidentTitle: z.string(),
+});
+export type SystemHealthOverride = z.infer<typeof SystemHealthOverrideSchema>;
+
 export const incidentContract = {
   /** List all incidents with optional filters */
   listIncidents: proc({
@@ -243,6 +256,27 @@ export const incidentContract = {
     .input(z.object({ systemId: z.string() }))
     .output(z.object({ suppressed: z.boolean() })),
 
+  /**
+   * Return, for each requested system, the health overrides contributed by its
+   * currently ACTIVE incidents (status != resolved, `healthOverride` set).
+   * Server-to-server read used by `@checkstack/healthcheck-backend` to fold
+   * incident overrides into a system's derived health via worst-wins. Systems
+   * with no active override are omitted from the record. Resolved incidents
+   * never appear, so an override auto-lifts the moment its incident resolves.
+   */
+  getActiveHealthOverrides: proc({
+    operationType: "query",
+    userType: "service",
+    access: [incidentAccess.incident.read],
+  })
+    .route({ method: "POST" })
+    .input(z.object({ systemIds: z.array(z.string()) }))
+    .output(
+      z.object({
+        overrides: z.record(z.string(), z.array(SystemHealthOverrideSchema)),
+      }),
+    ),
+
   /**
    * Open an incident on behalf of another plugin (no user context).
    * Used by automated systems like the health-check auto-incident flow.

package/src/schemas.ts

@@ -20,6 +20,22 @@ export type IncidentStatus = z.infer<typeof IncidentStatusEnum>;
 export const IncidentSeverityEnum = z.enum(["minor", "major", "critical"]);
 export type IncidentSeverity = z.infer<typeof IncidentSeverityEnum>;
 
+/**
+ * Optional health status an incident forces onto its affected systems while the
+ * incident is active (not resolved). It is a DELIBERATE user choice, independent
+ * of the incident's `severity` - the operator picks how the components should
+ * read on every health surface, not a value derived from impact ranking.
+ *
+ * Deliberately a subset of the health-check status vocabulary
+ * (`healthy | degraded | unhealthy`): forcing a system to `healthy` via an
+ * incident makes no sense, so only the two "problem" states are offered. The
+ * override folds into the system's health via worst-wins alongside the
+ * automated checks (see `@checkstack/healthcheck-backend`), so a check reporting
+ * something worse always wins.
+ */
+export const IncidentHealthOverrideEnum = z.enum(["degraded", "unhealthy"]);
+export type IncidentHealthOverride = z.infer<typeof IncidentHealthOverrideEnum>;
+
 /**
  * Core incident entity schema
  */
@@ -30,6 +46,12 @@ export const IncidentSchema = z.object({
   status: IncidentStatusEnum,
   severity: IncidentSeverityEnum,
   suppressNotifications: z.boolean(),
+  /**
+   * Optional health status forced onto the incident's affected systems while it
+   * is active. `null` (the default) means the incident does not touch derived
+   * system health. See {@link IncidentHealthOverrideEnum}.
+   */
+  healthOverride: IncidentHealthOverrideEnum.nullable(),
   createdAt: z.date(),
   updatedAt: z.date(),
 });
@@ -91,6 +113,11 @@ export const CreateIncidentInputSchema = z.object({
   description: z.string().optional(),
   severity: IncidentSeverityEnum,
   suppressNotifications: z.boolean().optional().default(false),
+  /**
+   * Optional health status to force onto the affected systems while the incident
+   * is active. Omit or pass `null` to leave derived system health untouched.
+   */
+  healthOverride: IncidentHealthOverrideEnum.nullable().optional(),
   systemIds: z.array(z.string()).min(1, "At least one system is required"),
   initialMessage: z
     .string()
@@ -114,6 +141,12 @@ export const UpdateIncidentInputSchema = z.object({
   description: z.string().nullable().optional(),
   severity: IncidentSeverityEnum.optional(),
   suppressNotifications: z.boolean().optional(),
+  /**
+   * Set to a status to force it, or `null` to clear a previously-set override.
+   * Omit to leave the current override unchanged (same nullable-optional
+   * clearing semantics as `description`).
+   */
+  healthOverride: IncidentHealthOverrideEnum.nullable().optional(),
   systemIds: z.array(z.string()).min(1).optional(),
 });
 export type UpdateIncidentInput = z.infer<typeof UpdateIncidentInputSchema>;

package/src/signals.test.ts

@@ -15,6 +15,7 @@ const baseIncident = (
   status: "investigating",
   severity: "critical",
   suppressNotifications: false,
+  healthOverride: null,
   createdAt: new Date("2026-06-01T10:00:00.000Z"),
   updatedAt: new Date("2026-06-01T10:00:00.000Z"),
   systemIds: ["sys-1"],