@checkstack/catalog-backend 1.3.0 → 1.4.0

package/src/router.ts

@@ -7,6 +7,8 @@ import {
   type SystemContact,
 } from "@checkstack/catalog-common";
 import { EntityService } from "./services/entity-service";
+import { diffSystemEnvironments } from "./services/environment-membership";
+import { isUniqueViolation } from "./services/pg-errors";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import { NotificationApi } from "@checkstack/notification-common";
@@ -233,6 +235,16 @@ export const createCatalogRouter = ({
   );
 
   const createSystem = os.createSystem.handler(async ({ input }) => {
+    // Reject duplicate names up front for a clean error on the common path.
+    // The DB also has a unique index on `name` (see migration 0004); the catch
+    // below converts a race-induced unique violation into the same CONFLICT.
+    const nameClash = await entityService.getSystemByName(input.name);
+    if (nameClash) {
+      throw new ORPCError("CONFLICT", {
+        message: `A system named "${input.name}" already exists`,
+      });
+    }
+
     // Drive the create through the reactive `catalog-system` entity (§10.4):
     // `apply` performs the REAL `systems` write (the plugin's own db/tx) and
     // returns the new reactive state; the deriver fires `catalog.created`
@@ -241,18 +253,27 @@ export const createCatalogRouter = ({
     // not-yet-existing row as absent.
     const systemId = crypto.randomUUID();
     let result!: Awaited<ReturnType<typeof entityService.createSystem>>;
-    await writeCatalogSystemEntity({
-      handle: getSystemEntity?.(),
-      systemId,
-      apply: async () => {
-        result = await entityService.createSystem(input, systemId);
-        return toCatalogSystemState({
-          name: result.name,
-          description: result.description,
-          metadata: result.metadata as Record<string, unknown> | null,
+    try {
+      await writeCatalogSystemEntity({
+        handle: getSystemEntity?.(),
+        systemId,
+        apply: async () => {
+          result = await entityService.createSystem(input, systemId);
+          return toCatalogSystemState({
+            name: result.name,
+            description: result.description,
+            metadata: result.metadata as Record<string, unknown> | null,
+          });
+        },
+      });
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new ORPCError("CONFLICT", {
+          message: `A system named "${input.name}" already exists`,
         });
-      },
-    });
+      }
+      throw error;
+    }
 
     // Push the new system into notification-backend's resource registry.
     // notification-backend handles all per-spec group provisioning from
@@ -297,6 +318,18 @@ export const createCatalogRouter = ({
       });
     }
 
+    // Renaming to a name another system already uses is rejected, so the
+    // create-side uniqueness guard cannot be sidestepped via rename. The DB
+    // unique index + the catch below cover the concurrent-rename race.
+    if (cleanData.name !== undefined) {
+      const nameClash = await entityService.getSystemByName(cleanData.name);
+      if (nameClash && nameClash.id !== input.id) {
+        throw new ORPCError("CONFLICT", {
+          message: `A system named "${cleanData.name}" already exists`,
+        });
+      }
+    }
+
     // Drive the update through the reactive `catalog-system` entity (§10.4).
     // The REAL update runs INSIDE `apply`, so `prev` is snapshotted before
     // the write and the deriver fires `catalog.updated` from the resulting
@@ -306,22 +339,31 @@ export const createCatalogRouter = ({
     let result!: NonNullable<
       Awaited<ReturnType<typeof entityService.updateSystem>>
     >;
-    await writeCatalogSystemEntity({
-      handle: getSystemEntity?.(),
-      systemId: input.id,
-      apply: async () => {
-        const updated = await entityService.updateSystem(input.id, cleanData);
-        if (!updated) {
-          throw new ORPCError("NOT_FOUND", { message: "System not found" });
-        }
-        result = updated;
-        return toCatalogSystemState({
-          name: result.name,
-          description: result.description,
-          metadata: result.metadata as Record<string, unknown> | null,
+    try {
+      await writeCatalogSystemEntity({
+        handle: getSystemEntity?.(),
+        systemId: input.id,
+        apply: async () => {
+          const updated = await entityService.updateSystem(input.id, cleanData);
+          if (!updated) {
+            throw new ORPCError("NOT_FOUND", { message: "System not found" });
+          }
+          result = updated;
+          return toCatalogSystemState({
+            name: result.name,
+            description: result.description,
+            metadata: result.metadata as Record<string, unknown> | null,
+          });
+        },
+      });
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new ORPCError("CONFLICT", {
+          message: `A system named "${cleanData.name ?? input.data.name}" already exists`,
         });
-      },
-    });
+      }
+      throw error;
+    }
 
     await cache.invalidateTopology();
     // Refresh display label in notification-backend on rename so the
@@ -659,6 +701,129 @@ export const createCatalogRouter = ({
       }),
   );
 
+  // ── Environments ──────────────────────────────────────────────────────
+  // Instance-wide catalog primitive. The drizzle `json()` metadata column is
+  // typed `unknown`; the contract expects `Record<string, unknown> | null`,
+  // so each handler narrows it the same way the system/group handlers do.
+  type EnvironmentRow = Awaited<
+    ReturnType<typeof entityService.getEnvironments>
+  >[number];
+  const toEnvironmentOutput = (environment: EnvironmentRow) =>
+    environment as EnvironmentRow & {
+      metadata: Record<string, unknown> | null;
+    };
+
+  const listEnvironments = os.listEnvironments.handler(async () => {
+    const environments = await entityService.getEnvironments();
+    return environments.map((environment) => toEnvironmentOutput(environment));
+  });
+
+  const getEnvironment = os.getEnvironment.handler(async ({ input }) => {
+    const environment = await entityService.getEnvironment(input.environmentId);
+    if (!environment) return null;
+    return toEnvironmentOutput(environment);
+  });
+
+  const createEnvironment = os.createEnvironment.handler(async ({ input }) => {
+    const created = await entityService.createEnvironment(input);
+    // New environments have no systems yet.
+    return toEnvironmentOutput({ ...created, systemIds: [] });
+  });
+
+  const updateEnvironment = os.updateEnvironment.handler(async ({ input }) => {
+    await enforceNotGitOpsLocked("Environment", input.environmentId);
+    const existing = await entityService.getEnvironment(input.environmentId);
+    if (!existing) {
+      throw new ORPCError("NOT_FOUND", { message: "Environment not found" });
+    }
+    const cleanData: Partial<{
+      name: string;
+      description?: string;
+      metadata?: Record<string, unknown>;
+    }> = {};
+    if (input.data.name !== undefined) cleanData.name = input.data.name;
+    if (input.data.description !== undefined) {
+      cleanData.description = input.data.description;
+    }
+    if (input.data.metadata !== undefined) {
+      cleanData.metadata = input.data.metadata;
+    }
+    await entityService.updateEnvironment(input.environmentId, cleanData);
+    const updated = await entityService.getEnvironment(input.environmentId);
+    if (!updated) {
+      throw new ORPCError("INTERNAL_SERVER_ERROR", {
+        message: "Environment not found after update",
+      });
+    }
+    return toEnvironmentOutput(updated);
+  });
+
+  const deleteEnvironment = os.deleteEnvironment.handler(async ({ input }) => {
+    await enforceNotGitOpsLocked("Environment", input.environmentId);
+    await entityService.deleteEnvironment(input.environmentId);
+    return { success: true };
+  });
+
+  const setSystemEnvironments = os.setSystemEnvironments.handler(
+    async ({ input }) => {
+      await enforceNotGitOpsLocked("System", input.systemId);
+      const current = await entityService.getEnvironmentsForSystem(
+        input.systemId,
+      );
+      const { toAdd, toRemove } = diffSystemEnvironments({
+        current: current.map((row) => row.environmentId),
+        desired: input.environmentIds,
+      });
+      for (const environmentId of toAdd) {
+        await entityService.addSystemToEnvironment({
+          environmentId,
+          systemId: input.systemId,
+        });
+      }
+      for (const environmentId of toRemove) {
+        await entityService.removeSystemFromEnvironment({
+          environmentId,
+          systemId: input.systemId,
+        });
+      }
+      return { success: true };
+    },
+  );
+
+  const getSystemEnvironments = os.getSystemEnvironments.handler(
+    async ({ input }) => {
+      const memberships = await entityService.getEnvironmentsForSystem(
+        input.systemId,
+      );
+      const environments = await entityService.getEnvironmentsByIds(
+        memberships.map((m) => m.environmentId),
+      );
+      return environments.map((environment) => toEnvironmentOutput(environment));
+    },
+  );
+
+  // Service-grade cross-plugin reads (healthcheck fan-out resolution).
+  const resolveSystemEnvironments = os.resolveSystemEnvironments.handler(
+    async ({ input }) => {
+      const memberships = await entityService.getEnvironmentsForSystem(
+        input.systemId,
+      );
+      const environments = await entityService.getEnvironmentsByIds(
+        memberships.map((m) => m.environmentId),
+      );
+      return environments.map((environment) => toEnvironmentOutput(environment));
+    },
+  );
+
+  const resolveEnvironments = os.resolveEnvironments.handler(
+    async ({ input }) => {
+      const environments = await entityService.getEnvironmentsByIds(
+        input.environmentIds,
+      );
+      return environments.map((environment) => toEnvironmentOutput(environment));
+    },
+  );
+
   // Build and return the router
   return os.router({
     getEntities,
@@ -683,6 +848,15 @@ export const createCatalogRouter = ({
     getViews,
     createView,
     getSystemGroupIds,
+    listEnvironments,
+    getEnvironment,
+    createEnvironment,
+    updateEnvironment,
+    deleteEnvironment,
+    setSystemEnvironments,
+    getSystemEnvironments,
+    resolveSystemEnvironments,
+    resolveEnvironments,
   });
 };
 

package/src/schema.ts

@@ -1,3 +1,4 @@
+import { sql } from "drizzle-orm";
 import {
   pgTable,
   pgEnum,
@@ -5,44 +6,78 @@ import {
   timestamp,
   json,
   primaryKey,
+  uniqueIndex,
 } from "drizzle-orm/pg-core";
 
 // Enums
 export const contactTypeEnum = pgEnum("contact_type", ["user", "mailbox"]);
 
 // Tables use pgTable (schemaless) - runtime schema is set via search_path
-export const systems = pgTable("systems", {
-  id: text("id").primaryKey(),
-  name: text("name").notNull(),
-  description: text("description"),
-  metadata: json("metadata").default({}),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-  updatedAt: timestamp("updated_at").defaultNow().notNull(),
-});
+export const systems = pgTable(
+  "systems",
+  {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    description: text("description"),
+    metadata: json("metadata").default({}),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // System names are unique, CASE-INSENSITIVELY ("Api" and "api" collide).
+    // A functional index on lower(name) enforces this at the DB while the stored
+    // value keeps its original casing.
+    nameUnique: uniqueIndex("systems_name_unique").on(sql`lower(${t.name})`),
+  }),
+);
 
-export const systemContacts = pgTable("system_contacts", {
-  id: text("id").primaryKey(),
-  systemId: text("system_id")
-    .notNull()
-    .references(() => systems.id, { onDelete: "cascade" }),
-  type: contactTypeEnum("type").notNull(),
-  // For type="user": userId references auth user
-  userId: text("user_id"),
-  // For type="mailbox": store email directly
-  email: text("email"),
-  // Optional label for display (e.g., "On-Call", "Team Lead")
-  label: text("label"),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-});
+export const systemContacts = pgTable(
+  "system_contacts",
+  {
+    id: text("id").primaryKey(),
+    systemId: text("system_id")
+      .notNull()
+      .references(() => systems.id, { onDelete: "cascade" }),
+    type: contactTypeEnum("type").notNull(),
+    // For type="user": userId references auth user
+    userId: text("user_id"),
+    // For type="mailbox": store email directly
+    email: text("email"),
+    // Optional label for display (e.g., "On-Call", "Team Lead")
+    label: text("label"),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // A given user, or a given mailbox email, may be attached to a system only
+    // once. NULLs are distinct in Postgres btree, so the two partial keys don't
+    // interfere: user contacts (email NULL) are deduped by (system, user) and
+    // mailbox contacts (userId NULL) by (system, email).
+    systemUserUnique: uniqueIndex("system_contacts_system_user_unique").on(
+      t.systemId,
+      t.userId,
+    ),
+    systemEmailUnique: uniqueIndex("system_contacts_system_email_unique").on(
+      t.systemId,
+      t.email,
+    ),
+  }),
+);
 
-export const groups = pgTable("groups", {
-  id: text("id").primaryKey(),
-  name: text("name").notNull(),
+export const groups = pgTable(
+  "groups",
+  {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
 
-  metadata: json("metadata").default({}),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-  updatedAt: timestamp("updated_at").defaultNow().notNull(),
-});
+    metadata: json("metadata").default({}),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // Group names are unique, CASE-INSENSITIVELY (consistent with systems.name).
+    nameUnique: uniqueIndex("groups_name_unique").on(sql`lower(${t.name})`),
+  }),
+);
 
 export const systemsGroups = pgTable(
   "systems_groups",
@@ -59,19 +94,70 @@ export const systemsGroups = pgTable(
   }),
 );
 
+/**
+ * Instance-wide environments. A sibling of `groups`: a free-form set of
+ * custom fields (baseUrl, region, tier, ...) that any system can belong to
+ * many-to-many. `metadata` reuses the same json+default({}) precedent as
+ * systems.metadata / groups.metadata; its values surface in templating
+ * verbatim. Unlike `groups`, environments carry a `description` (matching
+ * `systems`).
+ */
+export const environments = pgTable(
+  "environments",
+  {
+    id: text("id").primaryKey(),
+    name: text("name").notNull(),
+    description: text("description"),
+    metadata: json("metadata").default({}),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+    updatedAt: timestamp("updated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // Environment names are unique, CASE-INSENSITIVELY (like systems / groups).
+    nameUnique: uniqueIndex("environments_name_unique").on(
+      sql`lower(${t.name})`,
+    ),
+  }),
+);
+
+export const systemsEnvironments = pgTable(
+  "systems_environments",
+  {
+    systemId: text("system_id")
+      .notNull()
+      .references(() => systems.id, { onDelete: "cascade" }),
+    environmentId: text("environment_id")
+      .notNull()
+      .references(() => environments.id, { onDelete: "cascade" }),
+  },
+  (t) => ({
+    pk: primaryKey(t.systemId, t.environmentId),
+  }),
+);
+
 /**
  * Free-form hotlinks attached to a system — e.g. Jira board, dashboard URL,
  * runbook. Sits alongside contacts but is purely URL-based, no user/email.
  */
-export const systemLinks = pgTable("system_links", {
-  id: text("id").primaryKey(),
-  systemId: text("system_id")
-    .notNull()
-    .references(() => systems.id, { onDelete: "cascade" }),
-  label: text("label"),
-  url: text("url").notNull(),
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-});
+export const systemLinks = pgTable(
+  "system_links",
+  {
+    id: text("id").primaryKey(),
+    systemId: text("system_id")
+      .notNull()
+      .references(() => systems.id, { onDelete: "cascade" }),
+    label: text("label"),
+    url: text("url").notNull(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // The same URL may be attached to a system only once.
+    systemUrlUnique: uniqueIndex("system_links_system_url_unique").on(
+      t.systemId,
+      t.url,
+    ),
+  }),
+);
 
 export const views = pgTable("views", {
   id: text("id").primaryKey(),

package/src/services/entity-service.test.ts

@@ -81,4 +81,32 @@ describe("EntityService", () => {
     await service.deleteSystem("test");
     expect(mockDb.delete).toHaveBeenCalledWith(schema.systems);
   });
+
+  it("getSystemByName returns the matching system", async () => {
+    const row = {
+      id: "s1",
+      name: "Payments",
+      description: null,
+      status: "healthy" as "healthy" | "degraded" | "unhealthy",
+      metadata: {},
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    (mockDb.select as any).mockReturnValue({
+      from: mock(() => ({ where: mock(() => Promise.resolve([row])) })),
+    });
+
+    const result = await service.getSystemByName("Payments");
+    expect(result).toEqual(row);
+    expect(mockDb.select).toHaveBeenCalled();
+  });
+
+  it("getSystemByName returns undefined when the name is free", async () => {
+    (mockDb.select as any).mockReturnValue({
+      from: mock(() => ({ where: mock(() => Promise.resolve([])) })),
+    });
+
+    const result = await service.getSystemByName("Unused Name");
+    expect(result).toBeUndefined();
+  });
 });

package/src/services/entity-service.ts

@@ -1,4 +1,4 @@
-import { eq, and, inArray } from "drizzle-orm";
+import { eq, and, inArray, sql } from "drizzle-orm";
 import * as schema from "../schema";
 import { SafeDatabase } from "@checkstack/backend-api";
 import { v4 as uuidv4 } from "uuid";
@@ -49,6 +49,12 @@ type NewGroup = {
   metadata?: Record<string, unknown>;
 };
 
+type NewEnvironment = {
+  name: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+};
+
 type NewView = {
   name: string;
   type: string;
@@ -75,6 +81,22 @@ export class EntityService {
     return result[0];
   }
 
+  /**
+   * Look up a system by name, CASE-INSENSITIVELY. Used for the friendly
+   * pre-write uniqueness check on create/rename; the `systems_name_unique`
+   * functional index (`lower(name)`) is the actual race-safe guard, and this
+   * mirrors its case-folding so the pre-check catches "Api" vs "api" too (a
+   * case-sensitive `eq` would miss it and leave only the generic DB conflict).
+   * Returns the first match, or undefined when the name is free.
+   */
+  async getSystemByName(name: string) {
+    const result = await this.database
+      .select()
+      .from(schema.systems)
+      .where(sql`lower(${schema.systems.name}) = lower(${name})`);
+    return result[0];
+  }
+
   /**
    * Create a system.
    *
@@ -304,6 +326,137 @@ export class EntityService {
       );
   }
 
+  // Environments — instance-wide catalog primitive (M:N with systems)
+  async getEnvironments() {
+    const allEnvironments = await this.database
+      .select()
+      .from(schema.environments);
+
+    const associations = await this.database
+      .select()
+      .from(schema.systemsEnvironments);
+
+    const envSystemsMap = new Map<string, string[]>();
+    for (const assoc of associations) {
+      const existing = envSystemsMap.get(assoc.environmentId) ?? [];
+      existing.push(assoc.systemId);
+      envSystemsMap.set(assoc.environmentId, existing);
+    }
+
+    return allEnvironments.map((environment) => ({
+      ...environment,
+      systemIds: envSystemsMap.get(environment.id) ?? [],
+    }));
+  }
+
+  async getEnvironment(id: string) {
+    const rows = await this.database
+      .select()
+      .from(schema.environments)
+      .where(eq(schema.environments.id, id));
+    const environment = rows[0];
+    if (!environment) return;
+    const associations = await this.database
+      .select()
+      .from(schema.systemsEnvironments)
+      .where(eq(schema.systemsEnvironments.environmentId, id));
+    return {
+      ...environment,
+      systemIds: associations.map((a) => a.systemId),
+    };
+  }
+
+  /**
+   * Resolve a set of environment ids to their full records (with systemIds).
+   * Unknown ids are silently dropped. Used by the cross-plugin
+   * `resolveEnvironments` read for the explicit-subset fan-out case.
+   */
+  async getEnvironmentsByIds(ids: ReadonlyArray<string>) {
+    if (ids.length === 0) return [];
+    const rows = await this.database
+      .select()
+      .from(schema.environments)
+      .where(inArray(schema.environments.id, [...ids]));
+    if (rows.length === 0) return [];
+    const associations = await this.database
+      .select()
+      .from(schema.systemsEnvironments)
+      .where(inArray(schema.systemsEnvironments.environmentId, [...ids]));
+    const envSystemsMap = new Map<string, string[]>();
+    for (const assoc of associations) {
+      const existing = envSystemsMap.get(assoc.environmentId) ?? [];
+      existing.push(assoc.systemId);
+      envSystemsMap.set(assoc.environmentId, existing);
+    }
+    return rows.map((environment) => ({
+      ...environment,
+      systemIds: envSystemsMap.get(environment.id) ?? [],
+    }));
+  }
+
+  async createEnvironment(data: NewEnvironment, id: string = uuidv4()) {
+    const result = await this.database
+      .insert(schema.environments)
+      .values({ id, ...data })
+      .returning();
+    return result[0];
+  }
+
+  async updateEnvironment(id: string, data: Partial<NewEnvironment>) {
+    const result = await this.database
+      .update(schema.environments)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(schema.environments.id, id))
+      .returning();
+    return result[0];
+  }
+
+  async deleteEnvironment(id: string) {
+    await this.database
+      .delete(schema.environments)
+      .where(eq(schema.environments.id, id));
+  }
+
+  async getEnvironmentsForSystem(systemId: string) {
+    return this.database
+      .select()
+      .from(schema.systemsEnvironments)
+      .where(eq(schema.systemsEnvironments.systemId, systemId));
+  }
+
+  async getSystemsForEnvironment(environmentId: string) {
+    return this.database
+      .select()
+      .from(schema.systemsEnvironments)
+      .where(eq(schema.systemsEnvironments.environmentId, environmentId));
+  }
+
+  async addSystemToEnvironment(props: {
+    environmentId: string;
+    systemId: string;
+  }) {
+    const { environmentId, systemId } = props;
+    await this.database
+      .insert(schema.systemsEnvironments)
+      .values({ environmentId, systemId })
+      .onConflictDoNothing();
+  }
+
+  async removeSystemFromEnvironment(props: {
+    environmentId: string;
+    systemId: string;
+  }) {
+    const { environmentId, systemId } = props;
+    await this.database
+      .delete(schema.systemsEnvironments)
+      .where(
+        and(
+          eq(schema.systemsEnvironments.environmentId, environmentId),
+          eq(schema.systemsEnvironments.systemId, systemId),
+        ),
+      );
+  }
+
   // Views
   async getViews() {
     return this.database.select().from(schema.views);