@checkstack/catalog-common 2.2.3 → 2.3.1

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @checkstack/catalog-common
 
+## 2.3.1
+
+### Patch Changes
+
+- Updated dependencies [13373ce]
+  - @checkstack/common@0.14.0
+  - @checkstack/auth-common@0.8.1
+  - @checkstack/frontend-api@0.7.1
+  - @checkstack/notification-common@1.3.1
+
+## 2.3.0
+
+### Minor Changes
+
+- 9dcc848: Redesign the catalog into a group-first browse view and tabbed management tables, with inline health rollups.
+
+  - Browse view: the catalog home is a real read-only, scale-built experience - collapsible group sections (with member counts) plus a synthetic Ungrouped section, a shared toolbar (search, group/health/tag filters, density toggle), URL-backed view state (shareable deep links), polished empty states, and a manager-only "Manage catalog" link. Per-system status badges render through the existing `SystemStateBadgesSlot`; filtering is client-side over the loaded set.
+  - Management: redesigned as tabbed data tables (Systems / Groups / Environments) replacing the two-column drag-to-assign layout. Systems get multi-select + a bulk bar, inline health, and group + environment membership as removable chips with type-ahead pickers (portaled so they are never clipped); Groups get inline rename and member chips; Environments get a name / members / field-count table (CRUD gated by `catalog.environment.manage`). GitOps-locked rows stay read-only. Drag-and-drop (and `@dnd-kit` on this page) is removed; the management page also shares the browse toolbar.
+  - Inline health rollups: a new platform contract `CatalogBrowseHealthSlot` (`@checkstack/catalog-common`) - an additive optional slot catalog-frontend only consumes (a headless data boundary feeding group rollups + the health filter), with a catalog-owned `CatalogHealthStatus` vocabulary so catalog gains no health-plugin dependency. Group headers show a rollup pill derived from the reported status DATA (a system absent from the map is `"unknown"`, never healthy); all-healthy groups start collapsed. The health filter is wired on both toolbars and enables once a filler reports. healthcheck-frontend fills the slot by reusing dashboard-frontend's `SystemBadgeDataProvider`. When no health source is installed the slot is unfilled and the catalog stays fully functional.
+
+  This is a beta minor.
+
+- 9dcc848: Redesign the dashboard as an extensible "needs attention" overview, and normalize system state badges.
+
+  The dashboard now surfaces ONLY systems that need attention (degraded, unhealthy, breaching/at-risk SLO, under an incident or active maintenance, anomalous, or with a dependency problem) and hides everything healthy. A compact header summarises fleet health and filters by severity; each problem renders as an elevated card with one row per issue that deep-links to where the issue originates. A calm "all clear" state shows when nothing needs attention, a live "recent activity" feed sits below, and a "View catalog" link replaces the duplicated system list.
+
+  New platform contract `SystemSignalsSlot` (`@checkstack/catalog-common`): a headless, render-once slot where any plugin bulk-fetches and reports structured `SystemSignal[]` per system via `onSignals(sourceId, map)`. The dashboard aggregates every source agnostic to which plugins contribute; each core reliability plugin (healthcheck, incident, SLO, maintenance, anomaly, dependency) ships a filler, and third-party plugins add new per-system state the same way with no dashboard change. Signals carry an `iconName` rendered via `DynamicIcon` so the contract stays React-free. The dashboard's old summary tiles and overview sheets are removed, so it no longer depends on those plugins' packages. The group "subscribe" control moved onto the catalog browse page's group headers.
+
+  System state badges are normalized into one icon-only `@checkstack/ui` `StatusBadge` primitive - a small tinted icon chip with the full label on hover/focus (and via `aria-label`). Each signal uses its feature's navbar icon (health = Activity, incident = AlertTriangle, SLO = Target, maintenance = Wrench, dependency = GitBranch; anomaly = ChartSpline). Badges self-sort by severity via CSS `order` (error -> warn -> info), tooltips are scoped to a named group, and in catalog browse rows the cluster moved to the right edge.
+
+  This is a beta minor.
+
+- 9dcc848: Add environments as a first-class catalog primitive, with per-environment health-check fan-out, config templating, per-environment reactive health, and script run-context exposure.
+
+  - Catalog primitive: an environment is a sibling of groups - a named, instance-global record carrying free-form custom fields (baseUrl, region, tier, ...) that any system can belong to many-to-many. New `environments` + `systems_environments` tables, `EnvironmentSchema` + create/update schemas, `EntityService` environment CRUD and membership joins, RPC endpoints gated by a new `catalogAccess.environment` access rule, a GitOps `Environment` kind + `System.environments` extension, and frontend management (an `EnvironmentEditor`, an Environments management panel, and a per-system environment picker). The Environments card's Add/Edit/Delete affordances are gated on `catalogAccess.environment.manage`.
+  - Per-environment fan-out: run identity becomes `(systemId, configurationId, environmentId)`. Runs, aggregates, and state transitions gain a nullable `environmentId`. The health-check assignment gains an `environmentIds` selector with three modes (All / Specific / None; `null` and `[]` are distinct). The queue executor resolves the effective environment set via the catalog `resolveSystemEnvironments` read and executes one isolated run per environment.
+  - Config templating: a new `x-templatable` config-field marker renders a string field through the template engine at execute time, against `{ environment, check, system }`. A shared `renderTemplatableConfig` and a `renderTemplatePreview` helper (re-exported from `@checkstack/template-engine`) keep editor previews identical to the run-time render. The HTTP collector's `url`, `headers[].value`, and `body` are templatable, rendered per environment (the strategy client build moves inside the per-env loop); the `url`'s `.url()` validation moves post-render. Secrets resolve before templating; a field marked both secret and `x-templatable` is rejected at plugin load. `DynamicForm` shows a live "Preview" line, and the catalog `EnvironmentPreviewPicker` ("Preview as: <environment>") drives it in the collector editor (only when the schema has a templatable field).
+  - Script run-context: `CollectorRunContext` gains an optional `environment` field (`{ id, name, fields }`, metadata only). Shell collectors receive `CHECKSTACK_ENV_ID` / `_NAME` / `CHECKSTACK_ENV_<FIELD>` vars; inline TS collectors read `globalThis.context.environment`; the editor test panel mirrors both. The env-less path is unchanged.
+  - Per-environment reactive health (see BREAKING below), env-keyed read/write paths, env-qualified serialization locks, an optional `trigger.payload.environmentId`, per-environment isolation, and an `ENVIRONMENT_RESOLUTION_FAILED` signal when catalog resolution degrades to a single env-less run.
+
+  BREAKING CHANGES: the reactive `health` entity's id-shape and cardinality change. It now encodes two views: per-environment (id `"<systemId>::<environmentId>"`) and a system rollup (id `"<systemId>"`, the worst status across environments + env-less runs). The rollup PRESERVES the pre-existing system-level contract - dashboards, status badges, and automations referencing health by `systemId` keep working without re-authoring - but the entity's contract surface changed (new id-shape, higher cardinality, new payload field), so it is flagged breaking. `getBulkHealthState` parses env-qualified ids and keys results by the original id.
+
+  State and scale: membership and custom fields live only in catalog Postgres and are re-read every tick via the cross-plugin RPC; env-keyed health reads from shared `health_check_runs` / aggregates / transitions (compute-on-read). Every pod resolves the same effective set and the same per-environment health. No pod-local environment state.
+
+  Also: `unwrapSchema` in `zod-config.ts` loops instead of single-pass-stripping so multi-layer wrappers (`.optional().default()`) still resolve `x-templatable` meta. The env-less `{{ environment.* }}` run notice logs at `debug` (a legitimate recurring configuration), while the post-render HTTP `.url()` check still fails a genuinely-broken empty render with a clear "Rendered URL is invalid" error.
+
+  This is a beta minor.
+
+- 9dcc848: Input-validation and error-mapping hardening found by a fuzzing pass against the built container.
+
+  - backend: a Postgres driver error caused by bad client input no longer surfaces as a `500`. The `/api` and `/rest` dispatchers now map the relevant SQLSTATE classes to the correct status - `22P02`/`22003`/`22001`/`22007` (malformed/out-of-range/over-long/bad-date value), `23502`/`23503`/`23514` (missing/dangling/check-failed) to `400`, and `23505` (unique violation) to `409` - and log them at `warn` (client mistake), not `error`. The client-facing message is generic so column/constraint names are never leaked; genuine unknown faults still log at `error` and 500. Previously a `where id = $1` with a non-uuid `$1` (or an over-long string, or a foreign-key miss in `addSystemToGroup`) reached the driver and 500'd, making routine probing look like a server outage and burying real 500s.
+  - slo-common: **fixes a stored cluster-wide DoS.** `windowDays` was accepted up to `2^53`, but the SLO engine derives window boundaries with `Date(now - windowDays * 86_400_000)` - a large value overflows past the max representable `Date` and yields `Invalid Date`. That objective committed fine, then every subsequent read of the system's objectives threw `RangeError: Invalid time value` during serialization (a 500 readable by anyone with SLO read access, on any pod). `windowDays` is now bounded to 1..3650 days at the contract, the GitOps `kind: SLO` spec, and the update path via a single shared `SloWindowDaysSchema`, so the poison row can never be created.
+  - slo-common + healthcheck-common: SLO `getDailySnapshots` and the healthcheck history endpoints (`getHistory`, `getDetailedHistory`, `getAggregatedHistory`, `getDetailedAggregatedHistory`, `getRunsForAnalysis`) declared their `startDate`/`endDate` params as `z.date()`, which a `/rest/...` string param can never satisfy - so those endpoints 400'd on the entire REST surface. They now use `z.coerce.date()`, accepting both the REST string shape and the native RPC `Date`.
+  - healthcheck-common: `intervalSeconds` was `z.number().min(1)` with no `.int()` and no upper bound, so a fractional or out-of-range value reached the DB and failed at insert (the column is a 32-bit int). It is now `.int().min(1).max(2_592_000)` (1 second .. 30 days), applied to both create and update (the update schema is the create partial).
+  - catalog-common: system/group/environment names were bare `z.string()` (environment was `.min(1)` only), so empty, whitespace-only, and 100KB+ names reached the DB - the huge ones surfaced as 500s when parameter binding blew up. Names are now `trim().min(1).max(200)` via a shared schema.
+
+    **BREAKING:** `getSystemContacts` is now `userType: "authenticated"` (was `"public"`). System contacts carry PII (user id, name, email); the public read leaked them to anonymous status-page visitors. Anonymous callers now receive `401` for this one endpoint; the system detail page already renders "No contacts assigned" for anonymous viewers, so the UI degrades gracefully. All other catalog reads remain public.
+
+  - catalog-frontend: the system detail page skips the `getSystemContacts` request entirely for anonymous viewers (it would now `401`) and falls back to the empty state.
+
+  This is a beta release: the breaking contact-visibility change ships as a minor bump per the beta versioning policy, not a major.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/auth-common@0.8.0
+  - @checkstack/notification-common@1.3.0
+  - @checkstack/common@0.13.0
+  - @checkstack/frontend-api@0.7.0
+
 ## 2.2.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-common",
-  "version": "2.2.3",
+  "version": "2.3.1",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,17 +9,17 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.11.0",
-    "@checkstack/auth-common": "0.7.1",
-    "@checkstack/frontend-api": "0.5.2",
-    "@checkstack/notification-common": "1.2.0",
-    "@orpc/contract": "^1.13.14",
+    "@checkstack/common": "0.13.0",
+    "@checkstack/auth-common": "0.8.0",
+    "@checkstack/frontend-api": "0.7.0",
+    "@checkstack/notification-common": "1.3.0",
+    "@orpc/contract": "^1.14.4",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3"
+    "@checkstack/scripts": "0.4.0"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/access.ts

@@ -44,6 +44,24 @@ export const catalogAccess = {
     },
   }),
 
+  /**
+   * Environment access (global, no team-based filtering).
+   *
+   * Environments are an instance-wide catalog primitive (a sibling of
+   * groups): a free-form set of custom fields that any system can belong
+   * to many-to-many.
+   */
+  environment: accessPair("environment", {
+    read: {
+      description: "View environments",
+      isDefault: true,
+      isPublic: true,
+    },
+    manage: {
+      description: "Create, update, and delete environments",
+    },
+  }),
+
   /**
    * View access (global, user-only).
    */
@@ -66,6 +84,8 @@ export const catalogAccessRules = [
   catalogAccess.system.manage,
   catalogAccess.group.read,
   catalogAccess.group.manage,
+  catalogAccess.environment.read,
+  catalogAccess.environment.manage,
   catalogAccess.view.read,
   catalogAccess.view.manage,
 ];

package/src/rpc-contract.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import type { ZodType } from "zod";
+import { catalogContract } from "./rpc-contract";
+
+/**
+ * Contract-level guards for the fuzzing-pass findings:
+ * - `getSystemContacts` leaked PII (userId/userName/userEmail) to anonymous
+ *   callers because it was `userType: "public"`. It must be `authenticated`.
+ * - System/Group names were bare `z.string()`, so empty, whitespace-only, and
+ *   100KB+ names reached the DB (the huge ones surfaced as 500s).
+ *
+ * `~orpc` is the contract-procedure internals (same accessor the sandbox-policy
+ * access test uses); `meta.userType` and `inputSchema` are stable fields on it.
+ */
+function metaFor(procName: keyof typeof catalogContract): {
+  userType?: string;
+} {
+  const proc = catalogContract[procName] as unknown as Record<string, unknown>;
+  const orpc = proc["~orpc"] as { meta?: { userType?: string } };
+  return orpc.meta ?? {};
+}
+
+function inputSchemaFor(procName: keyof typeof catalogContract): ZodType {
+  const proc = catalogContract[procName] as unknown as Record<string, unknown>;
+  const orpc = proc["~orpc"] as { inputSchema?: ZodType };
+  if (!orpc.inputSchema) throw new Error(`${String(procName)} has no input`);
+  return orpc.inputSchema;
+}
+
+describe("getSystemContacts is gated to authenticated callers (PII)", () => {
+  test("userType is authenticated, not public", () => {
+    expect(metaFor("getSystemContacts").userType).toBe("authenticated");
+  });
+
+  test("anonymous-readable catalog reads stay public (no over-correction)", () => {
+    expect(metaFor("getEntities").userType).toBe("public");
+    expect(metaFor("getSystem").userType).toBe("public");
+  });
+});
+
+describe("catalog name validation", () => {
+  const cases: Array<keyof typeof catalogContract> = [
+    "createSystem",
+    "createGroup",
+  ];
+
+  for (const procName of cases) {
+    test(`${String(procName)} rejects an empty name`, () => {
+      expect(inputSchemaFor(procName).safeParse({ name: "" }).success).toBe(
+        false,
+      );
+    });
+
+    test(`${String(procName)} rejects a whitespace-only name`, () => {
+      expect(inputSchemaFor(procName).safeParse({ name: "   " }).success).toBe(
+        false,
+      );
+    });
+
+    test(`${String(procName)} rejects a name over 200 chars`, () => {
+      expect(
+        inputSchemaFor(procName).safeParse({ name: "a".repeat(201) }).success,
+      ).toBe(false);
+    });
+
+    test(`${String(procName)} trims a valid name`, () => {
+      const parsed = inputSchemaFor(procName).safeParse({ name: "  ok  " });
+      expect(parsed.success).toBe(true);
+      if (parsed.success) {
+        expect((parsed.data as { name: string }).name).toBe("ok");
+      }
+    });
+  }
+
+  test("updateSystem rejects a whitespace-only name when provided", () => {
+    const schema = inputSchemaFor("updateSystem");
+    expect(
+      schema.safeParse({ id: "s1", data: { name: "   " } }).success,
+    ).toBe(false);
+    // ...but omitting the name (partial update) is still allowed.
+    expect(schema.safeParse({ id: "s1", data: {} }).success).toBe(true);
+  });
+});

package/src/rpc-contract.ts

@@ -8,12 +8,26 @@ import {
   SystemContactSchema,
   ContactTypeSchema,
   SystemLinkSchema,
+  EnvironmentSchema,
+  CreateEnvironmentSchema,
+  UpdateEnvironmentSchema,
 } from "./types";
 import { catalogAccess } from "./access";
 
+// Shared catalog display-name validation. Bare `z.string()` previously let
+// empty, whitespace-only, and unbounded (100KB+) names through to the DB - the
+// huge ones surfaced as 500s (parameter binding blew up), the empty ones as
+// confusing rows. Trim first so " " collapses to "" and fails `.min(1)`; cap at
+// 200 chars (well inside the `systems.name` unique btree index limit).
+const NameSchema = z
+  .string()
+  .trim()
+  .min(1, "Name is required")
+  .max(200, "Name must be at most 200 characters");
+
 // Input schemas that match the service layer expectations
 const CreateSystemInputSchema = z.object({
-  name: z.string(),
+  name: NameSchema,
   description: z.string().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
@@ -21,21 +35,21 @@ const CreateSystemInputSchema = z.object({
 const UpdateSystemInputSchema = z.object({
   id: z.string(),
   data: z.object({
-    name: z.string().optional(),
+    name: NameSchema.optional(),
     description: z.string().nullable().optional(),
     metadata: z.record(z.string(), z.unknown()).nullable().optional(),
   }),
 });
 
 const CreateGroupInputSchema = z.object({
-  name: z.string(),
+  name: NameSchema,
   metadata: z.record(z.string(), z.unknown()).optional(),
 });
 
 const UpdateGroupInputSchema = z.object({
   id: z.string(),
   data: z.object({
-    name: z.string().optional(),
+    name: NameSchema.optional(),
     metadata: z.record(z.string(), z.unknown()).nullable().optional(),
   }),
 });
@@ -133,9 +147,13 @@ export const catalogContract = {
   // SYSTEM CONTACTS MANAGEMENT
   // ==========================================================================
 
+  // Gated to authenticated callers: contacts carry PII (userId, userName,
+  // userEmail). A "public" read leaked those to anonymous status-page visitors.
+  // The detail-page UI renders "No contacts assigned" when this returns empty,
+  // so anonymous viewers degrade gracefully rather than erroring.
   getSystemContacts: proc({
     operationType: "query",
-    userType: "public",
+    userType: "authenticated",
     access: [catalogAccess.system.read],
     instanceAccess: { idParam: "systemId" },
   })
@@ -267,6 +285,89 @@ export const catalogContract = {
     )
     .output(z.object({ success: z.boolean() })),
 
+  // ==========================================================================
+  // ENVIRONMENT MANAGEMENT
+  // Instance-wide catalog primitive: free-form custom fields, M:N with systems.
+  // ==========================================================================
+
+  listEnvironments: proc({
+    operationType: "query",
+    userType: "public",
+    access: [catalogAccess.environment.read],
+  }).output(z.array(EnvironmentSchema)),
+
+  getEnvironment: proc({
+    operationType: "query",
+    userType: "public",
+    access: [catalogAccess.environment.read],
+  })
+    .input(z.object({ environmentId: z.string() }))
+    .output(EnvironmentSchema.nullable()),
+
+  createEnvironment: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [catalogAccess.environment.manage],
+  })
+    .input(CreateEnvironmentSchema)
+    .output(EnvironmentSchema),
+
+  updateEnvironment: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [catalogAccess.environment.manage],
+  })
+    .route({ method: "PATCH" })
+    .input(
+      z.object({
+        environmentId: z.string(),
+        data: UpdateEnvironmentSchema,
+      }),
+    )
+    .output(EnvironmentSchema),
+
+  deleteEnvironment: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [catalogAccess.environment.manage],
+  })
+    .route({ method: "DELETE" })
+    .input(z.object({ environmentId: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /**
+   * Desired-set assignment of a system's environments. Diffs the supplied
+   * set against current membership: adds missing links, prunes stale ones
+   * (mirrors the GitOps System->environments reconcile).
+   */
+  setSystemEnvironments: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [catalogAccess.environment.manage],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(
+      z.object({
+        systemId: z.string(),
+        environmentIds: z.array(z.string()),
+      }),
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  /**
+   * Returns the environments a system currently belongs to (with custom
+   * fields). Used by host plugins to render the per-system environment
+   * picker. Server-side join — no client-side filtering needed.
+   */
+  getSystemEnvironments: proc({
+    operationType: "query",
+    userType: "public",
+    access: [catalogAccess.environment.read],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({ systemId: z.string() }))
+    .output(z.array(EnvironmentSchema)),
+
   // ==========================================================================
   // VIEW MANAGEMENT (userType: "user")
   // ==========================================================================
@@ -301,6 +402,32 @@ export const catalogContract = {
   })
     .input(z.object({ systemId: z.string() }))
     .output(z.object({ groupIds: z.array(z.string()) })),
+
+  /**
+   * Service-grade read of a system's current environments (id + name +
+   * custom fields). Called by the healthcheck plugin at run time to resolve
+   * the effective fan-out set. Backend-to-backend only.
+   */
+  resolveSystemEnvironments: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  })
+    .input(z.object({ systemId: z.string() }))
+    .output(z.array(EnvironmentSchema)),
+
+  /**
+   * Service-grade resolve of an explicit set of environment ids (the
+   * explicit-subset fan-out case). Unknown ids are silently dropped.
+   * Backend-to-backend only.
+   */
+  resolveEnvironments: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  })
+    .input(z.object({ environmentIds: z.array(z.string()) }))
+    .output(z.array(EnvironmentSchema)),
 };
 
 // Export contract type

package/src/slots.ts

@@ -1,4 +1,5 @@
 import { createSlot } from "@checkstack/frontend-api";
+import type { IconName } from "@checkstack/common";
 import type { System } from "./types";
 
 /**
@@ -73,6 +74,164 @@ export const SystemStateBadgesSlot = createSlot<{ system: System }>(
   "plugin.catalog.system-state-badges"
 );
 
+/**
+ * Catalog-owned health status vocabulary for the browse-view rollup. These are
+ * the only values a slot filler may report through {@link CatalogBrowseHealthSlot}.
+ *
+ * This is deliberately catalog's OWN enum, not an import of healthcheck's
+ * status enum: the catalog browse view must not depend on healthcheck. A filler
+ * (e.g. healthcheck-frontend) maps its own status into these values. `"unknown"`
+ * is never reported by a filler — it is the catalog-side default for a system
+ * the filler did not report a status for (no health source, or no checks wired).
+ */
+export type CatalogHealthStatus = "healthy" | "degraded" | "unhealthy";
+
+/**
+ * The shape a {@link CatalogBrowseHealthSlot} filler reports back to the catalog
+ * browse view: a per-system-id status map. Systems absent from the map are
+ * treated as `"unknown"` by the rollup (NEVER as healthy).
+ */
+export type CatalogHealthStatuses = Record<string, CatalogHealthStatus>;
+
+/**
+ * Context passed to a {@link CatalogBrowseHealthSlot} filler.
+ *
+ * - `systemIds` — every system id currently visible in the browse view, so the
+ *   filler can bulk-fetch their statuses in one request.
+ * - `onStatuses` — the filler reports the resolved statuses here. The catalog
+ *   browse view derives its group-level rollup (worst-of) and powers the health
+ *   filter from this DATA, NOT from any rendered badge: healthy systems emit no
+ *   badge, so "all healthy" can only be derived from the reported map.
+ *
+ * The filler renders nothing visible — it is a headless data boundary. Per-system
+ * badges continue to come from {@link SystemStateBadgesSlot}.
+ */
+export interface CatalogBrowseHealthSlotContext {
+  systemIds: string[];
+  onStatuses: (statuses: CatalogHealthStatuses) => void;
+}
+
+/**
+ * Optional platform contract for surfacing bulk system-health data inline on the
+ * catalog browse view WITHOUT coupling catalog to any health provider.
+ *
+ * - catalog-frontend only CONSUMES this slot: it renders the slot once (a headless
+ *   data boundary) and feeds the reported statuses into its group rollups + health
+ *   filter. When the slot is unfilled, group headers show counts only and the
+ *   health filter is disabled — catalog stays fully functional with no health
+ *   source installed.
+ * - A plugin FILLS this slot to supply statuses (e.g. healthcheck-frontend wraps
+ *   dashboard-frontend's existing SystemBadgeDataProvider and reports the
+ *   bulk-fetched health via `onStatuses`). All cross-plugin coupling lives on the
+ *   filler side; catalog gains no new dependency.
+ *
+ * @example
+ * // In a health provider plugin
+ * import { CatalogBrowseHealthSlot } from "@checkstack/catalog-common";
+ *
+ * extensions: [{
+ *   id: "my-plugin.catalog-browse-health",
+ *   slotId: CatalogBrowseHealthSlot.id,
+ *   component: ({ systemIds, onStatuses }) => (
+ *     <MyBulkHealthReporter systemIds={systemIds} onStatuses={onStatuses} />
+ *   ),
+ * }]
+ */
+export const CatalogBrowseHealthSlot =
+  createSlot<CatalogBrowseHealthSlotContext>(
+    "plugin.catalog.browse-health"
+  );
+
+/**
+ * Severity tone of a dashboard {@link SystemSignal}. Drives the signal's colour,
+ * its sort order in the overview (error before warn before info), and the
+ * severity counts shown in the overview header.
+ */
+export type SystemSignalTone = "error" | "warn" | "info";
+
+/**
+ * One piece of "needs attention" state a plugin reports about a system for the
+ * dashboard overview. A single source may emit several signals for one system
+ * (e.g. two open incidents). The dashboard aggregates signals across ALL
+ * plugins to decide which systems to surface, how to sort them (worst tone
+ * first), what to count in the header, and renders each one as a deep-linking
+ * row pointing at the page the issue originates from.
+ */
+export interface SystemSignal {
+  /**
+   * Stable id of the contributing source, e.g. "incident" / "slo" /
+   * "healthcheck". Used to de-duplicate a source's contribution when it
+   * re-reports (see {@link SystemSignalsSlotContext.onSignals}).
+   */
+  source: string;
+  /** Severity tone. */
+  tone: SystemSignalTone;
+  /** Short label, e.g. "Critical incident". */
+  label: string;
+  /** Optional longer context, e.g. the incident title or "2 of 3 checks failing". */
+  detail?: string;
+  /**
+   * Deep link (resolved route path) to where the issue originates. Omit when
+   * there is no more specific page than the system itself.
+   */
+  href?: string;
+  /** ISO timestamp the signal started — shown as a "since" hint and used as a sort tie-break. */
+  since?: string;
+  /** Lucide icon name (PascalCase), rendered by `@checkstack/ui`'s `DynamicIcon`. */
+  iconName?: IconName;
+}
+
+/**
+ * The per-system-id signal map a {@link SystemSignalsSlot} filler reports for
+ * the systems it was handed. Systems absent from the map have no signal from
+ * that source (i.e. healthy as far as that source is concerned).
+ */
+export type SystemSignalsMap = Record<string, SystemSignal[]>;
+
+/**
+ * Context passed to a {@link SystemSignalsSlot} filler.
+ *
+ * - `systemIds` — every system in the overview, so the filler can bulk-fetch
+ *   their state in a single request (no N+1).
+ * - `onSignals` — the filler reports its resolved per-system signals here,
+ *   tagged with its own stable `sourceId`. Re-reporting with the same
+ *   `sourceId` REPLACES that source's previous contribution (so a source that
+ *   reports an empty map clears its signals). The dashboard derives which
+ *   systems need attention purely from this DATA — healthy systems are simply
+ *   absent from every source's map.
+ *
+ * The filler renders nothing visible — it is a headless data boundary, exactly
+ * like {@link CatalogBrowseHealthSlot}.
+ */
+export interface SystemSignalsSlotContext {
+  systemIds: string[];
+  onSignals: (sourceId: string, signals: SystemSignalsMap) => void;
+}
+
+/**
+ * Extensible platform contract for the dashboard "needs attention" overview.
+ * Any plugin FILLS this slot to contribute per-system state signals; the
+ * dashboard CONSUMES it (rendering the slot once, headless) and aggregates
+ * every source's signals to surface, sort, count, and deep-link problem
+ * systems. A new plugin adds a whole new kind of state to the overview just by
+ * filling this slot — no dashboard change required.
+ *
+ * @example
+ * // In your plugin
+ * import { SystemSignalsSlot } from "@checkstack/catalog-common";
+ *
+ * extensions: [{
+ *   id: "my-plugin.system-signals",
+ *   slotId: SystemSignalsSlot.id,
+ *   component: ({ systemIds, onSignals }) => (
+ *     <MyBulkSignalReporter systemIds={systemIds} onSignals={onSignals} />
+ *   ),
+ * }]
+ */
+export const SystemSignalsSlot = createSlot<SystemSignalsSlotContext>(
+  "plugin.catalog.system-signals"
+);
+
 /**
  * Slot for extending the System Editor dialog with additional sections.
  * Only rendered when editing an existing system (not during creation).

package/src/types.ts

@@ -66,6 +66,27 @@ export const GroupSchema = z.object({
 });
 export type Group = z.infer<typeof GroupSchema>;
 
+export const EnvironmentSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  systemIds: z.array(z.string()), // Required field from the service layer
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type Environment = z.infer<typeof EnvironmentSchema>;
+
+export const CreateEnvironmentSchema = z.object({
+  name: z.string().trim().min(1).max(200),
+  description: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CreateEnvironment = z.infer<typeof CreateEnvironmentSchema>;
+
+export const UpdateEnvironmentSchema = CreateEnvironmentSchema.partial();
+export type UpdateEnvironment = z.infer<typeof UpdateEnvironmentSchema>;
+
 export const ViewSchema = z.object({
   id: z.string(),
   name: z.string(),