Merge pull request 'feat(ai-roles): импортируемый мультиязычный каталог ролей агента' (#222) from feature/agent-roles-catalog into develop

Reviewed-on: #222

apps/server/src/database/migrations/20260626T150000-ai-agent-roles-catalog-source.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // `source` links an imported role back to its catalog origin
+  // `{ slug, language, version }`. Nullable: null => a manually-created role
+  // (no catalog provenance). The version lets the admin UI offer an UPDATE when
+  // the catalog ships a newer revision of the same slug.
+  await db.schema
+    .alterTable('ai_agent_roles')
+    .addColumn('source', 'jsonb', (col) => col)
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('ai_agent_roles')
+    .dropColumn('source')
+    .execute();
+}

apps/server/src/database/migrations/20260626T160000-ai-agent-roles-catalog-source-unique.ts

@@ -0,0 +1,31 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  // A catalog-imported role is uniquely identified within a workspace by its
+  // `source.slug` + `source.language` (a multilingual catalog: the `ru` variant
+  // of a slug installed as `en` is a SEPARATE install — hence both keys). The
+  // import path skips a slug+language already installed using an in-memory
+  // snapshot (installedKeys), but two CONCURRENT imports of the same bundle each
+  // read a stale snapshot and would both insert the same slug+language,
+  // duplicating the role. This partial unique index is the database-level
+  // backstop: the second insert gets a 23505 the service treats as
+  // "already installed" (skip), so the two imports converge on ONE role.
+  //
+  // Partial on `source IS NOT NULL` so MANUALLY-created roles (source NULL) are
+  // unconstrained — there can be many of those. Also partial on
+  // `deleted_at IS NULL` (like the existing name-unique index) so a soft-deleted
+  // role does not block re-importing the same slug+language later, matching the
+  // app's snapshot (listByWorkspace filters out soft-deleted rows).
+  await sql`
+    CREATE UNIQUE INDEX IF NOT EXISTS ai_agent_roles_workspace_source_unique
+    ON ai_agent_roles (workspace_id, (source ->> 'slug'), (source ->> 'language'))
+    WHERE source IS NOT NULL AND deleted_at IS NULL
+  `.execute(db);
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .dropIndex('ai_agent_roles_workspace_source_unique')
+    .ifExists()
+    .execute();
+}

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.spec.ts

@@ -1,4 +1,4 @@
-import { AiAgentRoleRepo } from './ai-agent-roles.repo';
+import { AiAgentRoleRepo, parseSource } from './ai-agent-roles.repo';
 import type { KyselyDB } from '../../types/kysely.types';
 
 /**
@@ -132,4 +132,77 @@ describe('AiAgentRoleRepo insert/update auto-start columns', () => {
     expect(set2.mock.calls[0][0].launchMessage).toBeNull();
     expect('autoStart' in set2.mock.calls[0][0]).toBe(false);
   });
+
+  it('insert binds `source` (jsonb); update sets it only when present', async () => {
+    const { repo, values } = makeInsertRepo();
+    await repo.insert({
+      workspaceId: 'ws-1',
+      name: 'R',
+      instructions: 'do',
+      source: { slug: 'researcher', language: 'en', version: 1 },
+    });
+    // jsonbBind returns a RawBuilder for a non-empty object (not null).
+    expect(values.mock.calls[0][0].source).not.toBeNull();
+
+    const { repo: repo2, set } = makeUpdateRepo();
+    await repo2.update('r-1', 'ws-1', { name: 'X' });
+    expect('source' in set.mock.calls[0][0]).toBe(false);
+
+    const { repo: repo3, set: set3 } = makeUpdateRepo();
+    await repo3.update('r-1', 'ws-1', {
+      source: { slug: 's', language: 'en', version: 2 },
+    });
+    expect('source' in set3.mock.calls[0][0]).toBe(true);
+  });
+});
+
+/**
+ * parseSource is THE single form validator for the `source` jsonb column: a
+ * JSON-string (legacy double-encoded) is parsed; a FULLY-VALID object
+ * ({ slug, language, version }) passes through as a typed RoleSource; anything
+ * partial or wrong-shaped degrades to null (= manual role). This is the
+ * stricter-than-before guard that closes the drift where a weak `{}`/`{slug:123}`
+ * value used to be stamped as a valid source by the read path.
+ */
+describe('parseSource', () => {
+  it('parses a legacy double-encoded JSON string into the typed source', () => {
+    expect(
+      parseSource('{"slug":"researcher","language":"en","version":1}'),
+    ).toEqual({ slug: 'researcher', language: 'en', version: 1 });
+  });
+
+  it('passes a fully-valid already-parsed object through', () => {
+    const obj = { slug: 's', language: 'en', version: 2 };
+    expect(parseSource(obj)).toEqual(obj);
+  });
+
+  it('returns the typed RoleSource (extra keys tolerated) for a valid shape', () => {
+    const src = parseSource({ slug: 's', language: 'ru', version: 3 });
+    expect(src).not.toBeNull();
+    // Narrowed to RoleSource: the fields are present and correctly typed.
+    expect(src?.slug).toBe('s');
+    expect(src?.language).toBe('ru');
+    expect(src?.version).toBe(3);
+  });
+
+  it('null / array / non-object / unparseable string => null', () => {
+    expect(parseSource(null)).toBeNull();
+    expect(parseSource([1, 2])).toBeNull();
+    expect(parseSource(42)).toBeNull();
+    expect(parseSource('not json')).toBeNull();
+  });
+
+  it('partial / wrong-typed shapes => null (no weak-but-typed-as-valid drift)', () => {
+    // Empty object: no slug/language/version.
+    expect(parseSource({})).toBeNull();
+    // slug present but not a string.
+    expect(parseSource({ slug: 123, language: 'en', version: 1 })).toBeNull();
+    // slug only, missing language + version.
+    expect(parseSource({ slug: 'a' })).toBeNull();
+    // empty-string slug / language are not valid catalog keys.
+    expect(parseSource({ slug: '', language: 'en', version: 1 })).toBeNull();
+    expect(parseSource({ slug: 'a', language: '', version: 1 })).toBeNull();
+    // version must be a number, not a numeric string.
+    expect(parseSource({ slug: 'a', language: 'en', version: '1' })).toBeNull();
+  });
 });

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts

@@ -2,7 +2,7 @@ import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
 import { dbOrTx, jsonbBind, parseJsonbValue } from '../../utils';
-import { AiAgentRole } from '@docmost/db/types/entity.types';
+import { AiAgentRole, RoleSource } from '@docmost/db/types/entity.types';
 
 /** The jsonb shape persisted in `model_config` (loosely typed for the column). */
 type ModelConfigValue = Record<string, unknown> | null;
@@ -81,6 +81,8 @@ export class AiAgentRoleRepo {
       autoStart?: boolean;
       // null/'' => stored as null (client default launch message).
       launchMessage?: string | null;
+      // Catalog origin { slug, language, version } | null. null => manual role.
+      source?: Record<string, unknown> | null;
     },
     trx?: KyselyTransaction,
   ): Promise<AiAgentRole> {
@@ -103,6 +105,9 @@ export class AiAgentRoleRepo {
         autoStart: values.autoStart ?? true,
         // Empty string is treated as "no custom text" => null.
         launchMessage: values.launchMessage || null,
+        // Same cast reason as modelConfig (see above).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        source: jsonbBind(values.source) as any,
       })
       .returningAll()
       .executeTakeFirst();
@@ -124,6 +129,8 @@ export class AiAgentRoleRepo {
       autoStart?: boolean;
       // undefined => unchanged; null/'' => clear to null; string => set.
       launchMessage?: string | null;
+      // undefined => unchanged; null => clear; object => set.
+      source?: Record<string, unknown> | null;
     },
     trx?: KyselyTransaction,
   ): Promise<void> {
@@ -142,6 +149,9 @@ export class AiAgentRoleRepo {
       // Empty string clears to null (client default launch message).
       set.launchMessage = patch.launchMessage || null;
     }
+    if (patch.source !== undefined) {
+      set.source = jsonbBind(patch.source);
+    }
     await db
       .updateTable('aiAgentRoles')
       .set(set)
@@ -192,14 +202,46 @@ export function parseModelConfig(
   );
 }
 
-/** Normalize a DB row so `modelConfig` is always an object or null. The cast
- *  bridges parseModelConfig's concrete `Record | null` to the column's broad
- *  generated `JsonValue` type (an object is a valid JsonValue at runtime). */
+/**
+ * THE single form validator for the `source` jsonb column: parse the value read
+ * from the DB into a fully-valid {@link RoleSource} or null. Same legacy
+ * double-encoding self-heal as {@link parseModelConfig} (a JSON string is parsed
+ * once), then validates the FULL shape — `slug` and `language` non-empty
+ * strings, `version` a number. A null / corrupt / partially-shaped value (e.g.
+ * `{}`, `{ slug: 123 }`, `{ slug: 'a' }` missing language/version) degrades to
+ * null (= manually created, no catalog provenance), so a bad row never breaks
+ * the read path AND never stamps a half-built object as a valid `RoleSource`.
+ * Both the repo read-path and the service share this so the contract cannot
+ * drift between layers.
+ */
+export function parseSource(value: unknown): RoleSource | null {
+  return parseJsonbValue(value, isRoleSource);
+}
+
+/** Full-shape guard for a persisted `source` jsonb value (see parseSource). */
+function isRoleSource(v: unknown): v is RoleSource {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) return false;
+  const obj = v as Record<string, unknown>;
+  return (
+    typeof obj.slug === 'string' &&
+    obj.slug.length > 0 &&
+    typeof obj.language === 'string' &&
+    obj.language.length > 0 &&
+    typeof obj.version === 'number'
+  );
+}
+
+/** Normalize a DB row so `modelConfig` and `source` are always a valid object or
+ *  null. The casts bridge the concrete parsed types (`Record | null`,
+ *  `RoleSource | null`) to the column's broad generated `JsonValue` type — both
+ *  are valid JsonValues at runtime; RoleSource lacks the JsonObject index
+ *  signature so it routes through `unknown`. */
 function normalizeRow(row: AiAgentRole): AiAgentRole {
   return {
     ...row,
     modelConfig: parseModelConfig(
       row.modelConfig,
     ) as AiAgentRole['modelConfig'],
+    source: parseSource(row.source) as unknown as AiAgentRole['source'],
   };
 }

apps/server/src/database/types/db.d.ts

@@ -618,6 +618,8 @@ export interface AiAgentRoles {
   autoStart: Generated<boolean>;
   // Optional custom auto-start text. null/empty => client default launch message.
   launchMessage: string | null;
+  // Catalog origin of an imported role: { slug, language, version } | null. null => manually created.
+  source: Json | null;
   createdAt: Generated<Timestamp>;
   updatedAt: Generated<Timestamp>;
   deletedAt: Timestamp | null;

apps/server/src/database/types/entity.types.ts

@@ -81,6 +81,24 @@ export type UpdatableAiMcpServer = Updateable<Omit<AiMcpServersTable, 'id'>>;
 // A role replaces the persona layer of the system prompt (instructions) and may
 // optionally override the chat model (`modelConfig`). Soft-deletable.
 export type AiAgentRole = Selectable<AiAgentRoles>;
+
+/**
+ * The validated shape of the `source` jsonb column on ai_agent_roles: the
+ * catalog origin of an imported role. `version` lets the admin UI offer an
+ * UPDATE when the catalog ships a newer revision of the same slug; null `source`
+ * (not this type) means a manually-created role with no catalog provenance.
+ *
+ * THE single contract for that column, shared by the repo read-path
+ * (`parseSource`, the only form validator) and the service, so the persisted
+ * shape can never be validated weakly in one layer and strongly in another.
+ * Defined here (a leaf db-types module both already import `AiAgentRole` from) to
+ * avoid an import cycle between the repo and the service.
+ */
+export interface RoleSource {
+  slug: string;
+  language: string;
+  version: number;
+}
 export type InsertableAiAgentRole = Insertable<AiAgentRoles>;
 export type UpdatableAiAgentRole = Updateable<Omit<AiAgentRoles, 'id'>>;