@checkstack/dependency-backend 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,173 @@
 # @checkstack/dependency-backend
 
+## 1.1.0
+
+### Minor Changes
+
+- f6f9a5c: Add a GitOps `System.dependencies` extension and lock the matching UI.
+
+  Each entry references an upstream system by ref and tunes the impact:
+
+  ```yaml
+  apiVersion: checkstack.io/v1alpha1
+  kind: System
+  metadata: { name: payments-api }
+  spec:
+    dependencies:
+      - targetRef: { kind: System, name: payments-db }
+        impactType: critical
+        transitive: false
+        label: "primary store"
+  ```
+
+  The reconciler diffs the YAML-declared edges against the persisted ones
+  where this system is the source and converges via
+  create / update / delete. GitOps is the source of truth, so any edges
+  no longer listed are removed. Refs that resolve to the source system
+  itself are rejected; refs that fail to resolve abort the diff before
+  any mutation.
+
+  UI gates:
+
+  - The `DependencyEditor` (system editor drawer) hides Add and disables
+    Edit/Delete on upstream rows when the source system is GitOps-managed.
+    Downstream rows are gated per-row by the _other_ system's lock.
+  - The `DependencyMap` blocks `onConnect` when the source is locked,
+    surfaces a "Managed by GitOps" notice in the edge editor panel, and
+    disables Save/Delete there.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [f6f9a5c]
+- Updated dependencies [1ef2e79]
+  - @checkstack/common@0.9.0
+  - @checkstack/gitops-common@0.3.0
+  - @checkstack/gitops-backend@0.3.0
+  - @checkstack/incident-common@1.1.0
+  - @checkstack/maintenance-common@1.1.0
+  - @checkstack/catalog-common@2.1.0
+  - @checkstack/catalog-backend@1.1.0
+  - @checkstack/backend-api@0.15.1
+  - @checkstack/dependency-common@1.0.2
+  - @checkstack/healthcheck-backend@1.0.4
+  - @checkstack/healthcheck-common@1.0.2
+  - @checkstack/notification-common@1.0.2
+  - @checkstack/signal-common@0.2.2
+
+## 1.0.3
+
+### 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/backend-api@0.15.0
+  - @checkstack/catalog-backend@1.0.2
+  - @checkstack/catalog-common@2.0.1
+  - @checkstack/common@0.8.0
+  - @checkstack/dependency-common@1.0.1
+  - @checkstack/healthcheck-backend@1.0.3
+  - @checkstack/maintenance-common@1.0.1
+  - @checkstack/healthcheck-common@1.0.1
+  - @checkstack/incident-common@1.0.1
+  - @checkstack/notification-common@1.0.1
+  - @checkstack/signal-common@0.2.1
+
 ## 1.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@checkstack/dependency-backend",
-  "version": "1.0.2",
+  "version": "1.1.0",
+  "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -13,26 +14,28 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.14.0",
-    "@checkstack/dependency-common": "1.0.0",
-    "@checkstack/catalog-common": "2.0.0",
-    "@checkstack/catalog-backend": "1.0.0",
-    "@checkstack/healthcheck-common": "1.0.0",
-    "@checkstack/healthcheck-backend": "1.0.1",
-    "@checkstack/maintenance-common": "1.0.0",
-    "@checkstack/incident-common": "1.0.0",
-    "@checkstack/notification-common": "1.0.0",
-    "@checkstack/signal-common": "0.2.0",
-    "@checkstack/common": "0.7.0",
+    "@checkstack/backend-api": "0.15.0",
+    "@checkstack/dependency-common": "1.0.1",
+    "@checkstack/catalog-common": "2.0.1",
+    "@checkstack/catalog-backend": "1.0.2",
+    "@checkstack/healthcheck-common": "1.0.1",
+    "@checkstack/healthcheck-backend": "1.0.3",
+    "@checkstack/maintenance-common": "1.0.1",
+    "@checkstack/incident-common": "1.0.1",
+    "@checkstack/notification-common": "1.0.1",
+    "@checkstack/signal-common": "0.2.1",
+    "@checkstack/gitops-backend": "0.2.8",
+    "@checkstack/gitops-common": "0.2.2",
+    "@checkstack/common": "0.8.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
-    "@checkstack/drizzle-helper": "0.0.4",
-    "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.22",
-    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/drizzle-helper": "0.0.5",
+    "@checkstack/scripts": "0.3.0",
+    "@checkstack/test-utils-backend": "0.1.24",
+    "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/dependency-gitops-kinds.test.ts

@@ -0,0 +1,356 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import type { ReconcileContext } from "@checkstack/gitops-common";
+import type { Dependency } from "@checkstack/dependency-common";
+import type { DependencyService } from "./services/dependency-service";
+import { buildSystemDependenciesExtension } from "./dependency-gitops-kinds";
+
+const noopLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+const buildContext = (
+  overrides: Partial<ReconcileContext> = {},
+): ReconcileContext =>
+  ({
+    logger: noopLogger,
+    resolveEntityRef: async () => undefined,
+    resolveSecretsBySchema: async ({ value }) => ({
+      resolved: value,
+      warnings: [],
+    }),
+    ...overrides,
+  }) as ReconcileContext;
+
+const refResolver =
+  (table: Record<string, string>) =>
+  async ({ entityName }: { kind: string; entityName: string }) =>
+    table[entityName];
+
+const dep = (
+  id: string,
+  sourceSystemId: string,
+  targetSystemId: string,
+  overrides: Partial<Dependency> = {},
+): Dependency => ({
+  id,
+  sourceSystemId,
+  targetSystemId,
+  impactType: "degraded",
+  transitive: false,
+  label: null,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  ...overrides,
+});
+
+const stubService = (existing: Dependency[] = []) => {
+  let store = [...existing];
+  const getDependencies = mock(
+    async ({
+      systemId,
+      direction,
+    }: {
+      systemId: string;
+      direction?: "upstream" | "downstream" | "both";
+    }) => {
+      if (direction === "upstream") {
+        return store.filter((d) => d.sourceSystemId === systemId);
+      }
+      if (direction === "downstream") {
+        return store.filter((d) => d.targetSystemId === systemId);
+      }
+      return store.filter(
+        (d) => d.sourceSystemId === systemId || d.targetSystemId === systemId,
+      );
+    },
+  );
+  const createDependency = mock(
+    async (input: {
+      sourceSystemId: string;
+      targetSystemId: string;
+      impactType: "informational" | "degraded" | "critical";
+      transitive?: boolean;
+      label?: string;
+    }) => {
+      const created = dep(
+        `dep-${store.length + 1}`,
+        input.sourceSystemId,
+        input.targetSystemId,
+        {
+          impactType: input.impactType,
+          transitive: input.transitive ?? false,
+          label: input.label ?? null,
+        },
+      );
+      store.push(created);
+      return created;
+    },
+  );
+  const updateDependency = mock(
+    async (input: {
+      id: string;
+      systemId: string;
+      impactType?: "informational" | "degraded" | "critical";
+      transitive?: boolean;
+      label?: string | null;
+    }) => {
+      store = store.map((d) =>
+        d.id === input.id
+          ? {
+              ...d,
+              impactType: input.impactType ?? d.impactType,
+              transitive: input.transitive ?? d.transitive,
+              label: input.label === undefined ? d.label : input.label,
+            }
+          : d,
+      );
+      return store.find((d) => d.id === input.id);
+    },
+  );
+  const deleteDependency = mock(async (id: string) => {
+    const before = store.length;
+    store = store.filter((d) => d.id !== id);
+    return store.length < before;
+  });
+  return {
+    getDependencies,
+    createDependency,
+    updateDependency,
+    deleteDependency,
+    service: {
+      getDependencies,
+      createDependency,
+      updateDependency,
+      deleteDependency,
+    } as unknown as DependencyService,
+    get current() {
+      return store;
+    },
+  };
+};
+
+describe("buildSystemDependenciesExtension", () => {
+  let stub: ReturnType<typeof stubService>;
+  let extension: ReturnType<typeof buildSystemDependenciesExtension>;
+
+  beforeEach(() => {
+    stub = stubService();
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+  });
+
+  it("registers under System kind, namespace 'dependencies'", () => {
+    expect(extension.kind).toBe("System");
+    expect(extension.namespace).toBe("dependencies");
+  });
+
+  it("creates declared dependencies on first sync", async () => {
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "critical",
+          transitive: false,
+        },
+        {
+          targetRef: { kind: "System", name: "cache" },
+          impactType: "degraded",
+          transitive: true,
+          label: "fast path",
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db", cache: "sys-cache" }),
+      }),
+    });
+
+    expect(stub.createDependency).toHaveBeenCalledTimes(2);
+    expect(stub.createDependency).toHaveBeenNthCalledWith(1, {
+      sourceSystemId: "sys-payments",
+      targetSystemId: "sys-db",
+      impactType: "critical",
+      transitive: false,
+      label: undefined,
+      healthCheckRules: [],
+    });
+    expect(stub.createDependency).toHaveBeenNthCalledWith(2, {
+      sourceSystemId: "sys-payments",
+      targetSystemId: "sys-cache",
+      impactType: "degraded",
+      transitive: true,
+      label: "fast path",
+      healthCheckRules: [],
+    });
+  });
+
+  it("removes dependencies that are no longer declared", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db"),
+      dep("d2", "sys-payments", "sys-cache"),
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "degraded",
+          transitive: false,
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db" }),
+      }),
+    });
+
+    expect(stub.deleteDependency).toHaveBeenCalledTimes(1);
+    expect(stub.deleteDependency).toHaveBeenCalledWith("d2");
+    expect(stub.createDependency).not.toHaveBeenCalled();
+  });
+
+  it("updates an existing edge when impactType, transitive, or label changes", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db", {
+        impactType: "degraded",
+        transitive: false,
+        label: null,
+      }),
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "critical",
+          transitive: true,
+          label: "primary",
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db" }),
+      }),
+    });
+
+    expect(stub.updateDependency).toHaveBeenCalledWith({
+      id: "d1",
+      systemId: "sys-payments",
+      impactType: "critical",
+      transitive: true,
+      label: "primary",
+    });
+  });
+
+  it("is a no-op when an edge already matches the spec", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db", {
+        impactType: "critical",
+        transitive: false,
+        label: null,
+      }),
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [
+        {
+          targetRef: { kind: "System", name: "db" },
+          impactType: "critical",
+          transitive: false,
+        },
+      ],
+      context: buildContext({
+        resolveEntityRef: refResolver({ db: "sys-db" }),
+      }),
+    });
+
+    expect(stub.updateDependency).not.toHaveBeenCalled();
+    expect(stub.createDependency).not.toHaveBeenCalled();
+    expect(stub.deleteDependency).not.toHaveBeenCalled();
+  });
+
+  it("treats an empty/undefined spec as 'remove all my upstream deps'", async () => {
+    stub = stubService([
+      dep("d1", "sys-payments", "sys-db"),
+      dep("d2", "sys-other", "sys-payments"), // downstream — must NOT be touched
+    ]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await extension.reconcile({
+      entity: {} as never,
+      entityId: "sys-payments",
+      extensionSpec: [],
+      context: buildContext(),
+    });
+
+    expect(stub.deleteDependency).toHaveBeenCalledTimes(1);
+    expect(stub.deleteDependency).toHaveBeenCalledWith("d1");
+  });
+
+  it("rejects refs that resolve to the source system itself", async () => {
+    await expect(
+      extension.reconcile({
+        entity: {} as never,
+        entityId: "sys-payments",
+        extensionSpec: [
+          {
+            targetRef: { kind: "System", name: "self" },
+            impactType: "degraded",
+            transitive: false,
+          },
+        ],
+        context: buildContext({
+          resolveEntityRef: refResolver({ self: "sys-payments" }),
+        }),
+      }),
+    ).rejects.toThrow(/cannot depend on itself/);
+  });
+
+  it("aborts the diff when a ref cannot be resolved (no mutations)", async () => {
+    stub = stubService([dep("d1", "sys-payments", "sys-db")]);
+    extension = buildSystemDependenciesExtension({
+      getService: () => stub.service,
+    });
+
+    await expect(
+      extension.reconcile({
+        entity: {} as never,
+        entityId: "sys-payments",
+        extensionSpec: [
+          {
+            targetRef: { kind: "System", name: "missing" },
+            impactType: "degraded",
+            transitive: false,
+          },
+        ],
+        context: buildContext({
+          resolveEntityRef: async () => undefined,
+        }),
+      }),
+    ).rejects.toThrow(/Cannot resolve System ref "missing"/);
+
+    expect(stub.deleteDependency).not.toHaveBeenCalled();
+    expect(stub.createDependency).not.toHaveBeenCalled();
+    expect(stub.updateDependency).not.toHaveBeenCalled();
+  });
+});

package/src/dependency-gitops-kinds.ts

@@ -0,0 +1,173 @@
+import { z } from "zod";
+import {
+  CHECKSTACK_API_VERSION,
+  type EntityKindExtensionDefinition,
+  type EntityKindRegistry,
+  type ReconcileContext,
+} from "@checkstack/gitops-common";
+import { ImpactTypeSchema } from "@checkstack/dependency-common";
+import type { DependencyService } from "./services/dependency-service";
+
+interface DependencyGitOpsKindsDeps {
+  /** Lazy accessor — populated during init(), invoked at reconcile time. */
+  getService: () => DependencyService;
+}
+
+// ─── System.dependencies extension ──────────────────────────────────────────
+//
+// Declares upstream dependencies for a System. GitOps is the source of truth:
+// the reconciler diffs the YAML-declared edges against the persisted ones for
+// this system and applies create/update/delete to converge.
+//
+// `targetRef` references another System by name; `kind` is constrained to the
+// literal "System" so the relationship is self-documenting.
+
+const systemRefSchema = z
+  .object({
+    kind: z.literal("System"),
+    name: z.string().min(1),
+  })
+  .describe("Reference to the upstream System this system depends on.");
+
+const dependencyEntrySchema = z.object({
+  targetRef: systemRefSchema,
+  impactType: ImpactTypeSchema.optional().default("degraded"),
+  transitive: z.boolean().optional().default(false),
+  label: z.string().optional(),
+});
+
+const systemDependenciesExtensionSchema = z
+  .array(dependencyEntrySchema)
+  .optional();
+
+type SystemDependenciesExtension = z.infer<
+  typeof systemDependenciesExtensionSchema
+>;
+
+const edgeKey = (sourceId: string, targetId: string) =>
+  `${sourceId}->${targetId}`;
+
+export function buildSystemDependenciesExtension(
+  deps: DependencyGitOpsKindsDeps,
+): EntityKindExtensionDefinition<SystemDependenciesExtension> {
+  return {
+    apiVersion: CHECKSTACK_API_VERSION,
+    kind: "System",
+    namespace: "dependencies",
+    specSchema: systemDependenciesExtensionSchema,
+
+    reconcile: async ({
+      extensionSpec,
+      entityId,
+      context,
+    }: {
+      extensionSpec: SystemDependenciesExtension;
+      entityId: string;
+      context: ReconcileContext;
+    }) => {
+      const service = deps.getService();
+      const sourceSystemId = entityId;
+      const desired = extensionSpec ?? [];
+
+      // Resolve all target refs up-front so a single bad ref aborts the diff
+      // before we mutate anything.
+      const resolved: Array<{
+        targetSystemId: string;
+        impactType: "informational" | "degraded" | "critical";
+        transitive: boolean;
+        label: string | null;
+      }> = [];
+      for (const entry of desired) {
+        const targetSystemId = await context.resolveEntityRef({
+          kind: entry.targetRef.kind,
+          entityName: entry.targetRef.name,
+        });
+        if (!targetSystemId) {
+          throw new Error(
+            `Cannot resolve System ref "${entry.targetRef.name}" — ensure the upstream system exists`,
+          );
+        }
+        if (targetSystemId === sourceSystemId) {
+          throw new Error(
+            `Dependency target "${entry.targetRef.name}" resolves to the same system as the source — a system cannot depend on itself`,
+          );
+        }
+        resolved.push({
+          targetSystemId,
+          impactType: entry.impactType,
+          transitive: entry.transitive,
+          label: entry.label ?? null,
+        });
+      }
+
+      // Existing edges where this system is the source (upstream deps).
+      const existing = await service.getDependencies({
+        systemId: sourceSystemId,
+        direction: "upstream",
+      });
+
+      const existingByTarget = new Map(
+        existing.map((dep) => [edgeKey(dep.sourceSystemId, dep.targetSystemId), dep]),
+      );
+      const desiredKeys = new Set(
+        resolved.map((r) => edgeKey(sourceSystemId, r.targetSystemId)),
+      );
+
+      // Remove edges that are no longer declared.
+      for (const [key, dep] of existingByTarget) {
+        if (!desiredKeys.has(key)) {
+          await service.deleteDependency(dep.id);
+          context.logger.info(
+            `GitOps: removed dependency ${dep.sourceSystemId} → ${dep.targetSystemId}`,
+          );
+        }
+      }
+
+      // Add or update declared edges.
+      for (const entry of resolved) {
+        const key = edgeKey(sourceSystemId, entry.targetSystemId);
+        const current = existingByTarget.get(key);
+        if (!current) {
+          await service.createDependency({
+            sourceSystemId,
+            targetSystemId: entry.targetSystemId,
+            impactType: entry.impactType,
+            transitive: entry.transitive,
+            label: entry.label ?? undefined,
+            healthCheckRules: [],
+          });
+          context.logger.info(
+            `GitOps: created dependency ${sourceSystemId} → ${entry.targetSystemId} (${entry.impactType})`,
+          );
+          continue;
+        }
+
+        const needsUpdate =
+          current.impactType !== entry.impactType ||
+          current.transitive !== entry.transitive ||
+          (current.label ?? null) !== entry.label;
+        if (needsUpdate) {
+          await service.updateDependency({
+            id: current.id,
+            systemId: sourceSystemId,
+            impactType: entry.impactType,
+            transitive: entry.transitive,
+            label: entry.label,
+          });
+          context.logger.info(
+            `GitOps: updated dependency ${sourceSystemId} → ${entry.targetSystemId}`,
+          );
+        }
+      }
+    },
+  };
+}
+
+export function registerDependencyGitOpsKinds({
+  kindRegistry,
+  ...deps
+}: DependencyGitOpsKindsDeps & {
+  kindRegistry: EntityKindRegistry;
+}): void {
+  kindRegistry.registerKindExtension(buildSystemDependenciesExtension(deps));
+}

package/src/index.ts

@@ -20,6 +20,8 @@ import { NotificationApi } from "@checkstack/notification-common";
 import { catalogHooks } from "@checkstack/catalog-backend";
 import { healthCheckHooks } from "@checkstack/healthcheck-backend";
 import { evaluateAndNotifyDownstream } from "./notifications";
+import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
+import { registerDependencyGitOpsKinds } from "./dependency-gitops-kinds";
 
 // =============================================================================
 // Plugin Definition
@@ -34,6 +36,18 @@ export default createBackendPlugin({
       dependencyGroupSubscription,
     ]);
 
+    // ─── GitOps Entity Kind Registration ─────────────────────────────
+    let gitopsService: DependencyService | undefined;
+    const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
+    registerDependencyGitOpsKinds({
+      kindRegistry,
+      getService: () => {
+        if (!gitopsService)
+          throw new Error("DependencyService not initialized");
+        return gitopsService;
+      },
+    });
+
     env.registerInit({
       schema,
       deps: {
@@ -51,6 +65,7 @@ export default createBackendPlugin({
         const service = new DependencyService(
           database as SafeDatabase<typeof schema>,
         );
+        gitopsService = service;
         const warningService = new WarningEvaluationService();
 
         const router = createRouter({

package/src/router.ts

@@ -173,7 +173,7 @@ export function createRouter({
           systemStatuses: statuses,
         });
 
-        // eslint-disable-next-line unicorn/no-null -- oRPC contract requires null
+         
         return warningMap.get(input.systemId) ?? null;
       },
     ),

package/src/services/dependency-service.ts

@@ -97,7 +97,7 @@ export class DependencyService {
       targetSystemId: input.targetSystemId,
       impactType: input.impactType,
       transitive: input.transitive ?? false,
-      // eslint-disable-next-line unicorn/no-null -- Drizzle SQL column is nullable
+       
       label: input.label ?? null,
     });
 
@@ -213,7 +213,7 @@ export class DependencyService {
 
     return {
       ...row,
-      // eslint-disable-next-line unicorn/no-null -- Drizzle SQL column is nullable
+       
       label: row.label ?? null,
       healthCheckRules: rules.length > 0 ? rules : undefined,
     };
@@ -367,7 +367,7 @@ export class DependencyService {
       const rules = rulesByDep.get(row.id);
       return {
         ...row,
-        // eslint-disable-next-line unicorn/no-null -- Drizzle SQL column is nullable
+         
         label: row.label ?? null,
         healthCheckRules: rules && rules.length > 0 ? rules : undefined,
       };

package/tsconfig.json

@@ -22,6 +22,12 @@
     {
       "path": "../drizzle-helper"
     },
+    {
+      "path": "../gitops-backend"
+    },
+    {
+      "path": "../gitops-common"
+    },
     {
       "path": "../healthcheck-backend"
     },