@checkstack/dependency-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# @checkstack/dependency-common
+
+## 0.2.0
+
+### Minor Changes
+
+- 3f36a64: Add System Dependencies plugin
+
+  Introduces the system dependencies feature with three new core plugins and
+  extends the catalog with a new SystemEditorSlot extension point.
+
+  **New plugins:**
+
+  - **dependency-common**: Shared Zod schemas, RPC contract with resource-level access control, signal definitions, and routes
+  - **dependency-backend**: Drizzle schema, DependencyService with cycle detection, WarningEvaluationService with transitive impact matrix, RPC router with signal broadcasting, and per-user canvas node position persistence
+  - **dependency-frontend**: DependencyBadge (dashboard), DependencyAlert (system details), DependencyEditor (system editor dialog), and interactive DependencyMapPage (React Flow canvas)
+
+  **Catalog extensions:**
+
+  - **catalog-common**: New `SystemEditorSlot` for plugin-injected sections in the system editor dialog
+  - **catalog-frontend**: `SystemEditor` renders the slot after TeamAccessEditor for existing systems
+
+  **Key capabilities:**
+
+  - Directional dependency edges between systems (source depends on target)
+  - Three impact types: informational, degraded, critical
+  - Transitive multi-hop warning propagation with toggle switch
+  - Cycle detection at creation time with graphical chain visualization
+  - Health check-level dependency rules
+  - Interactive dependency map with drag-to-connect, edge click editor, and auto-saving node positions
+  - Inline editing of dependencies in both the system editor and the map canvas
+  - Team-based resource-level access control on all mutation endpoints
+  - Realtime signal-driven UI updates

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@checkstack/dependency-common",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.4",
+    "@checkstack/frontend-api": "0.3.8",
+    "@checkstack/signal-common": "0.1.8",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.4",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,36 @@
+import { accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Dependency plugin.
+ */
+export const dependencyAccess = {
+  /**
+   * Dependency access with both read and manage levels.
+   * Read is public by default so all users can see dependency warnings.
+   */
+  dependency: accessPair(
+    "dependency",
+    {
+      read: {
+        description: "View system dependencies and dependency warnings",
+        isDefault: true,
+        isPublic: true,
+      },
+      manage: {
+        description:
+          "Manage system dependencies - create, edit, and delete dependency relationships",
+      },
+    },
+    {
+      idParam: "systemId",
+    },
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const dependencyAccessRules = [
+  dependencyAccess.dependency.read,
+  dependencyAccess.dependency.manage,
+];

package/src/index.ts

@@ -0,0 +1,61 @@
+export { dependencyAccess, dependencyAccessRules } from "./access";
+export {
+  dependencyContract,
+  DependencyApi,
+  type DependencyContract,
+} from "./rpc-contract";
+export {
+  ImpactTypeSchema,
+  DerivedStateSchema,
+  HealthCheckRuleSchema,
+  DependencySchema,
+  AffectedUpstreamSchema,
+  DependencyWarningSchema,
+  CreateHealthCheckRuleInputSchema,
+  CreateDependencyInputSchema,
+  UpdateDependencyInputSchema,
+  NodePositionSchema,
+  type ImpactType,
+  type DerivedState,
+  type HealthCheckRule,
+  type Dependency,
+  type AffectedUpstream,
+  type DependencyWarning,
+  type CreateDependencyInput,
+  type UpdateDependencyInput,
+  type NodePosition,
+} from "./schemas";
+export * from "./plugin-metadata";
+export { dependencyRoutes } from "./routes";
+
+// =============================================================================
+// REALTIME SIGNALS
+// =============================================================================
+
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+
+/**
+ * Broadcast when dependency definitions change (created, updated, deleted).
+ * Frontend components can refetch the dependency graph.
+ */
+export const DEPENDENCY_CHANGED = createSignal(
+  "dependency.changed",
+  z.object({
+    dependencyId: z.string(),
+    sourceSystemId: z.string(),
+    targetSystemId: z.string(),
+    action: z.enum(["created", "updated", "deleted"]),
+  }),
+);
+
+/**
+ * Broadcast when computed dependency warnings change for one or more systems.
+ * Badge components listen to this to refresh without polling.
+ */
+export const DEPENDENCY_WARNINGS_CHANGED = createSignal(
+  "dependency.warnings.changed",
+  z.object({
+    affectedSystemIds: z.array(z.string()),
+  }),
+);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the dependency plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "dependency",
+});

package/src/routes.ts

@@ -0,0 +1,29 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the dependency plugin.
+ * The Dependency Map page is registered under the Catalog namespace.
+ *
+ * @example Frontend plugin usage
+ * ```tsx
+ * import { dependencyRoutes } from "@checkstack/dependency-common";
+ *
+ * createFrontendPlugin({
+ *   routes: [
+ *     { route: dependencyRoutes.routes.map, element: <DependencyMapPage /> },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Link generation
+ * ```tsx
+ * import { dependencyRoutes } from "@checkstack/dependency-common";
+ * import { resolveRoute } from "@checkstack/common";
+ *
+ * const mapPath = resolveRoute(dependencyRoutes.routes.map);
+ * ```
+ */
+export const dependencyRoutes = createRoutes("dependency", {
+  map: "/map",
+  systemDependencies: "/system/:systemId",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { dependencyAccess } from "./access";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  DependencySchema,
+  DependencyWarningSchema,
+  CreateDependencyInputSchema,
+  UpdateDependencyInputSchema,
+  NodePositionSchema,
+} from "./schemas";
+
+export const dependencyContract = {
+  // ==========================================================================
+  // READ ENDPOINTS (public - accessible by anyone with read access)
+  // ==========================================================================
+
+  /** Get all dependencies for a system (both directions) */
+  getDependencies: proc({
+    operationType: "query",
+    userType: "public",
+    access: [dependencyAccess.dependency.read],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(
+      z.object({
+        systemId: z.string(),
+        direction: z
+          .enum(["upstream", "downstream", "both"])
+          .optional()
+          .default("both"),
+      }),
+    )
+    .output(z.object({ dependencies: z.array(DependencySchema) })),
+
+  /** Get the full dependency graph (all dependencies, for the canvas) */
+  getAllDependencies: proc({
+    operationType: "query",
+    userType: "public",
+    access: [dependencyAccess.dependency.read],
+  }).output(z.object({ dependencies: z.array(DependencySchema) })),
+
+  /** Bulk-fetch derived warnings for multiple systems (for dashboard badges) */
+  getWarnings: proc({
+    operationType: "query",
+    userType: "public",
+    access: [dependencyAccess.dependency.read],
+  })
+    .input(z.object({ systemIds: z.array(z.string()) }))
+    .output(
+      z.object({
+        warnings: z.record(z.string(), DependencyWarningSchema),
+      }),
+    ),
+
+  /** Get dependency warnings for a single system */
+  getWarningsForSystem: proc({
+    operationType: "query",
+    userType: "public",
+    access: [dependencyAccess.dependency.read],
+  })
+    .input(z.object({ systemId: z.string() }))
+    .output(DependencyWarningSchema.nullable()),
+
+  // ==========================================================================
+  // MANAGEMENT ENDPOINTS (authenticated with manage access)
+  // ==========================================================================
+
+  /** Create a new dependency with cycle detection */
+  createDependency: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [dependencyAccess.dependency.manage],
+    instanceAccess: { idParam: "sourceSystemId" },
+  })
+    .input(CreateDependencyInputSchema)
+    .output(DependencySchema),
+
+  /** Update an existing dependency */
+  updateDependency: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [dependencyAccess.dependency.manage],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(UpdateDependencyInputSchema)
+    .output(DependencySchema),
+
+  /** Delete a dependency */
+  deleteDependency: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [dependencyAccess.dependency.manage],
+    instanceAccess: { idParam: "systemId" },
+  })
+    .input(z.object({ id: z.string(), systemId: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // NODE POSITIONS (authenticated - per-user canvas layout persistence)
+  // ==========================================================================
+
+  /** Get saved node positions for the dependency map canvas */
+  getNodePositions: proc({
+    operationType: "query",
+    userType: "user",
+    access: [dependencyAccess.dependency.read],
+  }).output(z.object({ positions: z.array(NodePositionSchema) })),
+
+  /** Save node positions for the dependency map canvas */
+  saveNodePositions: proc({
+    operationType: "mutation",
+    userType: "user",
+    access: [dependencyAccess.dependency.read],
+  })
+    .input(z.object({ positions: z.array(NodePositionSchema) }))
+    .output(z.object({ success: z.boolean() })),
+};
+
+// Export contract type
+export type DependencyContract = typeof dependencyContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(DependencyApi);
+export const DependencyApi = createClientDefinition(
+  dependencyContract,
+  pluginMetadata,
+);

package/src/schemas.ts

@@ -0,0 +1,148 @@
+import { z } from "zod";
+
+// =============================================================================
+// ENUMS
+// =============================================================================
+
+/**
+ * Impact type determines how an upstream system's status affects the downstream.
+ * - informational: Show a link/badge, no status impact
+ * - degraded: Downstream shows as degraded when upstream is affected
+ * - critical: Downstream shows as degraded when upstream is degraded, down when upstream is down
+ */
+export const ImpactTypeSchema = z.enum([
+  "informational",
+  "degraded",
+  "critical",
+]);
+export type ImpactType = z.infer<typeof ImpactTypeSchema>;
+
+/**
+ * Derived warning state computed from dependency evaluation.
+ */
+export const DerivedStateSchema = z.enum(["info", "degraded", "down"]);
+export type DerivedState = z.infer<typeof DerivedStateSchema>;
+
+// =============================================================================
+// HEALTH CHECK RULE
+// =============================================================================
+
+/**
+ * Optional advanced rule linking a dependency to a specific health check.
+ * When rules exist on a dependency, only specified checks trigger the impact.
+ */
+export const HealthCheckRuleSchema = z.object({
+  id: z.string(),
+  dependencyId: z.string(),
+  healthCheckId: z.string(),
+  overrideImpactType: ImpactTypeSchema,
+});
+export type HealthCheckRule = z.infer<typeof HealthCheckRuleSchema>;
+
+// =============================================================================
+// DEPENDENCY ENTITY
+// =============================================================================
+
+/**
+ * Core dependency entity representing a directional edge between two systems.
+ * sourceSystemId (downstream) depends on targetSystemId (upstream).
+ */
+export const DependencySchema = z.object({
+  id: z.string(),
+  sourceSystemId: z.string(),
+  targetSystemId: z.string(),
+  impactType: ImpactTypeSchema,
+  transitive: z.boolean(),
+  label: z.string().nullable(),
+  healthCheckRules: z.array(HealthCheckRuleSchema).optional(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type Dependency = z.infer<typeof DependencySchema>;
+
+// =============================================================================
+// DEPENDENCY WARNING (Computed, not persisted)
+// =============================================================================
+
+/**
+ * Information about a single affected upstream system contributing to a warning.
+ */
+export const AffectedUpstreamSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string(),
+  ownStatus: z.string(),
+  impactType: ImpactTypeSchema,
+  dependencyLabel: z.string().nullable(),
+});
+export type AffectedUpstream = z.infer<typeof AffectedUpstreamSchema>;
+
+/**
+ * Computed dependency warning for a system.
+ * Represents the worst derived state across all upstream dependencies.
+ */
+export const DependencyWarningSchema = z.object({
+  systemId: z.string(),
+  derivedState: DerivedStateSchema,
+  affectedUpstreams: z.array(AffectedUpstreamSchema),
+});
+export type DependencyWarning = z.infer<typeof DependencyWarningSchema>;
+
+// =============================================================================
+// INPUT SCHEMAS
+// =============================================================================
+
+/**
+ * Input for creating a health check rule within a dependency.
+ */
+export const CreateHealthCheckRuleInputSchema = z.object({
+  healthCheckId: z.string(),
+  overrideImpactType: ImpactTypeSchema,
+});
+
+/**
+ * Input for creating a new dependency.
+ */
+export const CreateDependencyInputSchema = z
+  .object({
+    sourceSystemId: z.string().min(1, "Source system is required"),
+    targetSystemId: z.string().min(1, "Target system is required"),
+    impactType: ImpactTypeSchema,
+    transitive: z.boolean().optional().default(false),
+    label: z.string().optional(),
+    healthCheckRules: z
+      .array(CreateHealthCheckRuleInputSchema)
+      .optional()
+      .default([]),
+  })
+  .refine(
+    ({ sourceSystemId, targetSystemId }) => sourceSystemId !== targetSystemId,
+    { message: "A system cannot depend on itself" },
+  );
+export type CreateDependencyInput = z.infer<typeof CreateDependencyInputSchema>;
+
+/**
+ * Input for updating an existing dependency.
+ */
+export const UpdateDependencyInputSchema = z.object({
+  id: z.string(),
+  systemId: z.string(),
+  impactType: ImpactTypeSchema.optional(),
+  transitive: z.boolean().optional(),
+  label: z.string().nullable().optional(),
+  healthCheckRules: z.array(CreateHealthCheckRuleInputSchema).optional(),
+});
+export type UpdateDependencyInput = z.infer<typeof UpdateDependencyInputSchema>;
+
+// =============================================================================
+// NODE POSITION (persisted server-side for the dependency map canvas)
+// =============================================================================
+
+/**
+ * Persisted node position for the dependency map canvas.
+ */
+export const NodePositionSchema = z.object({
+  systemId: z.string(),
+  x: z.number(),
+  y: z.number(),
+});
+export type NodePosition = z.infer<typeof NodePositionSchema>;

package/tests/schemas.test.ts

@@ -0,0 +1,96 @@
+import { describe, test, expect } from "bun:test";
+import {
+  CreateDependencyInputSchema,
+  ImpactTypeSchema,
+  DerivedStateSchema,
+} from "@checkstack/dependency-common";
+
+describe("dependency-common schemas", () => {
+  describe("ImpactTypeSchema", () => {
+    test("accepts valid impact types", () => {
+      expect(ImpactTypeSchema.parse("informational")).toBe("informational");
+      expect(ImpactTypeSchema.parse("degraded")).toBe("degraded");
+      expect(ImpactTypeSchema.parse("critical")).toBe("critical");
+    });
+
+    test("rejects invalid impact types", () => {
+      expect(() => ImpactTypeSchema.parse("invalid")).toThrow();
+    });
+  });
+
+  describe("DerivedStateSchema", () => {
+    test("accepts valid derived states", () => {
+      expect(DerivedStateSchema.parse("info")).toBe("info");
+      expect(DerivedStateSchema.parse("degraded")).toBe("degraded");
+      expect(DerivedStateSchema.parse("down")).toBe("down");
+    });
+
+    test("rejects invalid derived states", () => {
+      expect(() => DerivedStateSchema.parse("invalid")).toThrow();
+    });
+  });
+
+  describe("CreateDependencyInputSchema", () => {
+    test("accepts valid input", () => {
+      const input = CreateDependencyInputSchema.parse({
+        sourceSystemId: "sys-a",
+        targetSystemId: "sys-b",
+        impactType: "degraded",
+      });
+
+      expect(input.sourceSystemId).toBe("sys-a");
+      expect(input.targetSystemId).toBe("sys-b");
+      expect(input.impactType).toBe("degraded");
+      expect(input.transitive).toBe(false); // default
+      expect(input.healthCheckRules).toEqual([]); // default
+    });
+
+    test("rejects self-referencing dependency", () => {
+      expect(() =>
+        CreateDependencyInputSchema.parse({
+          sourceSystemId: "sys-a",
+          targetSystemId: "sys-a",
+          impactType: "degraded",
+        }),
+      ).toThrow("A system cannot depend on itself");
+    });
+
+    test("rejects empty source system", () => {
+      expect(() =>
+        CreateDependencyInputSchema.parse({
+          sourceSystemId: "",
+          targetSystemId: "sys-b",
+          impactType: "degraded",
+        }),
+      ).toThrow();
+    });
+
+    test("rejects empty target system", () => {
+      expect(() =>
+        CreateDependencyInputSchema.parse({
+          sourceSystemId: "sys-a",
+          targetSystemId: "",
+          impactType: "degraded",
+        }),
+      ).toThrow();
+    });
+
+    test("accepts health check rules", () => {
+      const input = CreateDependencyInputSchema.parse({
+        sourceSystemId: "sys-a",
+        targetSystemId: "sys-b",
+        impactType: "degraded",
+        healthCheckRules: [
+          {
+            healthCheckId: "hc-1",
+            overrideImpactType: "critical",
+          },
+        ],
+      });
+
+      expect(input.healthCheckRules).toHaveLength(1);
+      expect(input.healthCheckRules[0].healthCheckId).toBe("hc-1");
+      expect(input.healthCheckRules[0].overrideImpactType).toBe("critical");
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}