Address PR #222 re-review: fix source-uniqueness detection + coverage/cleanups

MUST-FIX
- isSourceUniqueViolation read the wrong error field: kysely-postgres-js
  (postgres@3.4.8) puts the violated constraint on `constraint_name`, not
  node-postgres' `.constraint`, so a concurrent same-slug+language import's
  23505 was never recognized as a source-collision and surfaced a false
  "name already exists" error. Now read `constraint_name` (with `.constraint`
  as a fallback for other drivers). Fix the faked test fixture (it built the
  error with the same wrong `.constraint` field, masking the bug): it now
  uses `constraint_name`, so the test genuinely exercises the skip path and
  FAILS against the unfixed code.
- Extract the catalog modal's role-state computation into a pure
  `catalogRoleInstallState(role, workspaceRoles, language)` helper (mirrors
  role-launch.ts) and cover it with vitest: import / installed / update /
  same-slug-different-language.

SUGGESTIONS
- Restore IAiRoleUpdateFromCatalogResult as a discriminated union mirroring
  the server; narrow the consumer via `"reason" in result` (the boolean
  discriminant does not narrow under strictNullChecks:false).
- README: add a "How it's served" section documenting AI_AGENT_ROLES_CATALOG_URL
  (remote http(s) base / local path / empty => in-repo folder).
- check.mjs: drop the redundant `const key = slug` alias.
- Cover the reason->message mapping in useUpdateAiRoleFromCatalogMutation
  (4 branches) via renderHook with a mocked service.
- Cover importFromCatalog "bundle not in index" => BadGateway.
- Cover updateFromCatalog "slug in index but missing in bundle file" =>
  not-in-catalog.

ARCHITECTURE
- Extract the shared catalog read prefix: a private `loadBundleById`
  (fetchIndex -> meta -> fetchBundle -> versionMap) reused by getCatalogBundle
  and importFromCatalog, and a `catalogRoleContentFields` mapper shared by the
  import insert and update patch. The three orchestrations and their distinct
  write paths stay separate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/client/src/features/ai-chat/queries/ai-chat-query.ts

@@ -319,15 +319,19 @@ export function useUpdateAiRoleFromCatalogMutation() {
       // The server returns updated:false with a reason for a no-op (already
       // up to date / removed from catalog / language no longer offered). Map
       // each reason to a specific message instead of a generic "up to date".
+      // Narrow the discriminated union via `"reason" in result` (the `updated`
+      // boolean discriminant does not narrow under this project's
+      // strictNullChecks:false). Inside the branch, `reason` is the typed literal
+      // union, so the comparisons below are compiler-checked.
       let message: string;
-      if (result.updated) {
+      if (!("reason" in result)) {
         message = t("Updated to the latest version");
       } else if (result.reason === "not-in-catalog") {
         message = t("This role is no longer in the catalog");
       } else if (result.reason === "language-unavailable") {
         message = t("This language is no longer available in the catalog");
       } else {
-        // "up-to-date" and any unexpected reason.
+        // "up-to-date" (the only remaining reason).
         message = t("Already up to date");
       }
       notifications.show({ message });

apps/client/src/features/ai-chat/queries/update-from-catalog-message.test.tsx

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import React from "react";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { IAiRoleUpdateFromCatalogResult } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+// `useUpdateAiRoleFromCatalogMutation` maps the server's discriminated result to
+// a user-facing notification message. These tests pin each of the four branches
+// (updated / not-in-catalog / language-unavailable / up-to-date) via renderHook
+// with a mocked service (precedent: share-query.null-normalization.test.tsx).
+
+const notificationsShowMock = vi.fn();
+vi.mock("@mantine/notifications", () => ({
+  notifications: { show: (opts: unknown) => notificationsShowMock(opts) },
+}));
+
+// `t` echoes the key so we assert against the exact English message strings.
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+vi.mock("@/features/ai-chat/services/ai-chat-service.ts", () => ({
+  updateAiRoleFromCatalog: vi.fn(),
+  // Other named exports referenced by ai-chat-query.ts must exist on the mock so
+  // the module import resolves; they are unused by these tests.
+  createAiRole: vi.fn(),
+  deleteAiChat: vi.fn(),
+  deleteAiRole: vi.fn(),
+  getAiChatMessages: vi.fn(),
+  getAiChats: vi.fn(),
+  getAiRoleCatalog: vi.fn(),
+  getAiRoleCatalogBundle: vi.fn(),
+  getAiRoles: vi.fn(),
+  importAiRolesFromCatalog: vi.fn(),
+  renameAiChat: vi.fn(),
+  updateAiRole: vi.fn(),
+}));
+
+import { updateAiRoleFromCatalog } from "@/features/ai-chat/services/ai-chat-service.ts";
+import { useUpdateAiRoleFromCatalogMutation } from "@/features/ai-chat/queries/ai-chat-query.ts";
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+  });
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+async function runMutation(result: IAiRoleUpdateFromCatalogResult) {
+  vi.mocked(updateAiRoleFromCatalog).mockResolvedValue(result);
+  const { result: hook } = renderHook(
+    () => useUpdateAiRoleFromCatalogMutation(),
+    { wrapper: createWrapper() },
+  );
+  hook.current.mutate("role-1");
+  await waitFor(() => expect(hook.current.isSuccess).toBe(true));
+}
+
+describe("useUpdateAiRoleFromCatalogMutation — reason → message", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("updated:true -> 'Updated to the latest version'", async () => {
+    await runMutation({
+      updated: true,
+      fromVersion: 1,
+      toVersion: 2,
+      role: { id: "role-1" } as never,
+    });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "Updated to the latest version",
+    });
+  });
+
+  it("not-in-catalog -> 'This role is no longer in the catalog'", async () => {
+    await runMutation({ updated: false, reason: "not-in-catalog" });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "This role is no longer in the catalog",
+    });
+  });
+
+  it("language-unavailable -> 'This language is no longer available in the catalog'", async () => {
+    await runMutation({ updated: false, reason: "language-unavailable" });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "This language is no longer available in the catalog",
+    });
+  });
+
+  it("up-to-date -> 'Already up to date'", async () => {
+    await runMutation({ updated: false, reason: "up-to-date" });
+    expect(notificationsShowMock).toHaveBeenCalledWith({
+      message: "Already up to date",
+    });
+  });
+});

apps/client/src/features/ai-chat/types/ai-chat.types.ts

@@ -116,14 +116,19 @@ export interface IAiRoleImportResult {
   errors: { slug: string; message: string }[];
 }
 
-/** Update-from-catalog result (mirrors `updateFromCatalog()`). */
-export interface IAiRoleUpdateFromCatalogResult {
-  updated: boolean;
-  fromVersion?: number;
-  toVersion?: number;
-  reason?: string;
-  role?: IAiRole;
-}
+/**
+ * Update-from-catalog result (mirrors the server `updateFromCatalog()`). A
+ * discriminated union on `updated`: a no-op carries a typed `reason` the UI maps
+ * to a specific message; a successful update carries the version bump + new role.
+ * Keeping the union (not a widened `reason?: string`) lets the consumer's literal
+ * comparisons be compiler-checked.
+ */
+export type IAiRoleUpdateFromCatalogResult =
+  | {
+      updated: false;
+      reason: "not-in-catalog" | "up-to-date" | "language-unavailable";
+    }
+  | { updated: true; fromVersion: number; toVersion: number; role: IAiRole };
 
 /** Admin create payload for a role. */
 export interface IAiRoleCreate {

apps/client/src/features/ai-chat/utils/catalog-role-install-state.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest";
+import { catalogRoleInstallState } from "./catalog-role-install-state.ts";
+import type { IAiRole } from "@/features/ai-chat/types/ai-chat.types.ts";
+
+// Build a workspace role with a catalog source. Fields irrelevant to the
+// install-state decision are filled with harmless defaults.
+function installedRole(
+  source: { slug: string; language: string; version: number },
+  overrides: Partial<IAiRole> = {},
+): IAiRole {
+  return {
+    id: `role-${source.slug}-${source.language}`,
+    name: source.slug,
+    emoji: null,
+    description: null,
+    enabled: true,
+    autoStart: true,
+    launchMessage: null,
+    source,
+    ...overrides,
+  };
+}
+
+const catalogRole = { slug: "writer", version: 3 };
+
+// Mirrors the role-launch.ts precedent: the modal's role-state computation is a
+// pure function so the import/installed/update decision is testable directly.
+describe("catalogRoleInstallState", () => {
+  it("no matching installed role -> import", () => {
+    const result = catalogRoleInstallState(catalogRole, [], "en");
+    expect(result).toEqual({ state: "import" });
+  });
+
+  it("same slug + language, installed version > catalog -> installed", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 5,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({ state: "installed", installed });
+  });
+
+  it("same slug + language, installed version == catalog -> installed", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 3,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({ state: "installed", installed });
+  });
+
+  it("same slug + language, installed version < catalog -> update (from/to)", () => {
+    const installed = installedRole({
+      slug: "writer",
+      language: "en",
+      version: 1,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({
+      state: "update",
+      installed,
+      fromVersion: 1,
+      toVersion: 3,
+    });
+  });
+
+  it("same slug but DIFFERENT language -> import (a separate install)", () => {
+    // 'writer' is installed in 'ru'; browsing the 'en' catalog must offer it as a
+    // fresh import, not treat the ru copy as already installed.
+    const installed = installedRole({
+      slug: "writer",
+      language: "ru",
+      version: 5,
+    });
+    const result = catalogRoleInstallState(catalogRole, [installed], "en");
+    expect(result).toEqual({ state: "import" });
+  });
+
+  it("matches the right language when the same slug is installed in several", () => {
+    const ru = installedRole(
+      { slug: "writer", language: "ru", version: 5 },
+      { id: "ru-role" },
+    );
+    const en = installedRole(
+      { slug: "writer", language: "en", version: 1 },
+      { id: "en-role" },
+    );
+    const result = catalogRoleInstallState(catalogRole, [ru, en], "en");
+    expect(result).toEqual({
+      state: "update",
+      installed: en,
+      fromVersion: 1,
+      toVersion: 3,
+    });
+  });
+
+  it("ignores manually-created roles (no source) sharing the name", () => {
+    const manual = installedRole(
+      { slug: "writer", language: "en", version: 9 },
+      { source: null },
+    );
+    const result = catalogRoleInstallState(catalogRole, [manual], "en");
+    expect(result).toEqual({ state: "import" });
+  });
+});

apps/client/src/features/ai-chat/utils/catalog-role-install-state.ts

@@ -0,0 +1,49 @@
+import type {
+  IAiRole,
+  IAiRoleCatalogRole,
+} from "@/features/ai-chat/types/ai-chat.types.ts";
+
+/**
+ * The install state of a single catalog role relative to the workspace's
+ * existing roles. Extracted as a pure function so the catalog modal's role-state
+ * computation is unit-testable without mounting the component (mirrors the
+ * `roleLaunchMessage` precedent in role-launch.ts).
+ *
+ * A catalog role is matched to an installed role by BOTH `source.slug` and
+ * `source.language`: the same slug in a different language is a separate install
+ * (so it shows as "import", not "installed"). When matched, the installed source
+ * version decides the state:
+ *   - no match                          -> "import"
+ *   - matched & installed version >= catalog version -> "installed"
+ *   - matched & installed version <  catalog version -> "update" (from -> to)
+ */
+export type CatalogRoleInstallState =
+  | { state: "import" }
+  | { state: "installed"; installed: IAiRole }
+  | {
+      state: "update";
+      installed: IAiRole;
+      fromVersion: number;
+      toVersion: number;
+    };
+
+export function catalogRoleInstallState(
+  role: Pick<IAiRoleCatalogRole, "slug" | "version">,
+  workspaceRoles: IAiRole[],
+  language: string,
+): CatalogRoleInstallState {
+  const installed = workspaceRoles.find(
+    (r) => r.source?.slug === role.slug && r.source?.language === language,
+  );
+  if (!installed) return { state: "import" };
+  const fromVersion = installed.source?.version ?? 0;
+  if (fromVersion >= role.version) {
+    return { state: "installed", installed };
+  }
+  return {
+    state: "update",
+    installed,
+    fromVersion,
+    toVersion: role.version,
+  };
+}

apps/client/src/features/workspace/components/settings/components/ai-agent-roles-catalog-modal.tsx

@@ -27,6 +27,7 @@ import {
   IAiRoleCatalogBundleSummary,
   IAiRoleCatalogRole,
 } from "@/features/ai-chat/types/ai-chat.types.ts";
+import { catalogRoleInstallState } from "@/features/ai-chat/utils/catalog-role-install-state.ts";
 
 interface AiAgentRolesCatalogModalProps {
   opened: boolean;
@@ -230,19 +231,14 @@ function BundlePanel({
   const updateMutation = useUpdateAiRoleFromCatalogMutation();
 
   // Compute each catalog role's install state against the current workspace
-  // roles: an importable role matched by source.slug + source.language.
+  // roles (matched by source.slug + source.language). The decision lives in the
+  // pure `catalogRoleInstallState` helper so it is unit-tested directly.
   const computed = useMemo(() => {
     const list = bundleQuery.data?.roles ?? [];
-    return list.map((role) => {
-      const installed = roles.find(
-        (r) => r.source?.slug === role.slug && r.source?.language === language,
-      );
-      if (!installed) return { role, state: "import" as const };
-      if ((installed.source?.version ?? 0) >= role.version) {
-        return { role, state: "installed" as const, installed };
-      }
-      return { role, state: "update" as const, installed };
-    });
+    return list.map((role) => ({
+      role,
+      ...catalogRoleInstallState(role, roles, language),
+    }));
   }, [bundleQuery.data, roles, language]);
 
   // Default-check every importable role once the bundle content arrives (unless
@@ -300,17 +296,23 @@ function BundlePanel({
 
         {bundleQuery.data && (
           <Stack gap="xs">
-            {computed.map(({ role, state, installed }) => (
+            {computed.map((entry) => (
               <CatalogRoleRow
-                key={role.slug}
-                role={role}
-                state={state}
-                checked={state === "import" ? !!selected?.has(role.slug) : false}
-                onToggle={(checked) => onToggleSlug(role.slug, checked)}
-                fromVersion={installed?.source?.version}
+                key={entry.role.slug}
+                role={entry.role}
+                state={entry.state}
+                checked={
+                  entry.state === "import"
+                    ? !!selected?.has(entry.role.slug)
+                    : false
+                }
+                onToggle={(checked) => onToggleSlug(entry.role.slug, checked)}
+                fromVersion={
+                  entry.state === "update" ? entry.fromVersion : undefined
+                }
                 onUpdate={
-                  state === "update" && installed
-                    ? () => updateMutation.mutate(installed.id)
+                  entry.state === "update"
+                    ? () => updateMutation.mutate(entry.installed.id)
                     : undefined
                 }
                 updating={updateMutation.isPending}