@things-factory/board-ai 10.0.0-beta.108

package/server/service/board-ai-resolver.ts

@@ -0,0 +1,407 @@
+/**
+ * GraphQL resolver — AI 주도 보드 모델링 (chat).
+ *
+ * Mutation: boardAIChat — 자연어 채팅. sessionId 가 있으면 메시지/패치 영속.
+ * sessionId 가 없으면 ad-hoc 모드로 단발 호출 (영속 없음).
+ */
+import { Resolver, Mutation, Arg, Ctx, Directive, Field, InputType, Int, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import '@things-factory/auth-base'
+
+import { config } from '@things-factory/env'
+import { getRepository } from '@things-factory/shell'
+import { createAIClient, getDefaultAIClient, type AIClient } from '@things-factory/ai-client-base'
+import type { ComponentCategory } from '@things-factory/board-import'
+
+import { DefaultBoardAIAssistant } from './assistant.js'
+import type { LLMMessage } from './types.js'
+import { ChatSession } from './chat-session/chat-session.js'
+import { ChatMessage } from './chat-message/chat-message.js'
+import { publishChatMessage } from './chat-message/chat-message-publish.js'
+import { PatchEntry } from './patch-entry/patch-entry.js'
+import { publishBoardPatch } from './patch-entry/board-patch-subscription.js'
+import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
+import { buildInviteNotification } from './chat-session-participant/invite-notification.js'
+import {
+  injectMentionRefids,
+  injectAiMentionRefids,
+  stripMentionRefids,
+  extractMentionUserIds,
+  newParticipantUserIds
+} from './mention-marker.js'
+
+@InputType()
+class BoardAILLMMessageInput {
+  @Field({ description: "Role: 'user' or 'assistant'" })
+  role: string
+
+  @Field({ description: 'Message content' })
+  content: string
+}
+
+@InputType()
+class BoardAIMentionPickInput {
+  @Field({ description: 'Token used by user (e.g. "경광등1" — the part after #).' })
+  token: string
+
+  @Field(() => Int, {
+    description:
+      'Refid explicitly picked from popup. Server uses this for deterministic resolution — bypasses fallback name/id/type matching for this token.'
+  })
+  refid: number
+}
+
+@InputType()
+class BoardAIChatInput {
+  @Field({
+    nullable: true,
+    description: 'ChatSession id. Omit for ad-hoc (no persistence). When given, messages/patches are persisted.'
+  })
+  sessionId?: string
+
+  @Field(() => [BoardAILLMMessageInput], {
+    description: 'Conversation history (latest user message at the end). For persisted sessions, only the last user message is appended; older are loaded from DB.'
+  })
+  messages: BoardAILLMMessageInput[]
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'Current BoardModel JSON.' })
+  currentBoard?: any
+
+  @Field(() => [String], {
+    nullable: true,
+    description:
+      "Capability scopes the AI is allowed to use (e.g. 'create', 'edit', 'style'). Filters which tools are exposed to the LLM."
+  })
+  scopes?: string[]
+
+  @Field(() => [String], {
+    nullable: true,
+    description: 'Component types the LLM is allowed to emit (e.g. ["rect", "label"]). Constrains generation to the current solution.'
+  })
+  knownTypes?: string[]
+
+  @Field(() => [String], {
+    nullable: true,
+    description: 'Component categories to surface (e.g. ["3D", "form"]). Subset filter for groupings exposed in component-schemas.'
+  })
+  categories?: string[]
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Component schemas — array of { type, description?, group?, properties? } so the LLM knows valid props per type.'
+  })
+  componentSchemas?: any
+
+  @Field(() => [Int], {
+    nullable: true,
+    description:
+      'Refids of components currently selected in the modeller (universal numeric handle, things-scene auto-assigned). For "selected" / "선택한" intent. Note: distinct from `id` which is a data-binding name.'
+  })
+  selectedRefids?: number[]
+
+  @Field(() => [BoardAIMentionPickInput], {
+    nullable: true,
+    description:
+      'Explicit #mention picks from popup — {token, refid}. User text stays clean (#token only); these picks let server resolve deterministically without exposing refid in the user-visible message. Tokens not in this list fall back to free name/id/type matching.'
+  })
+  mentions?: BoardAIMentionPickInput[]
+
+  @Field({
+    nullable: true,
+    description: 'AI model identifier override (e.g. "claude-opus-4-7"). Falls back to the configured default when omitted.'
+  })
+  model?: string
+
+  @Field({
+    nullable: true,
+    description: 'Sampling temperature override. Falls back to assistant default when omitted.'
+  })
+  temperature?: number
+
+  @Field({
+    nullable: true,
+    description: 'Max output tokens override per LLM call. Falls back to assistant default when omitted.'
+  })
+  maxTokens?: number
+}
+
+@ObjectType()
+class BoardAIChatOutput {
+  @Field({ description: 'Conversational reply.' })
+  reply: string
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'BoardEditPatch.' })
+  patch?: any
+
+  @Field({ nullable: true, description: 'Clarifying question when input is ambiguous.' })
+  followUp?: string
+
+  @Field({ description: 'AI client identifier (provider:model).' })
+  clientId: string
+
+  @Field({ nullable: true, description: 'Echo of session id (when persisted).' })
+  sessionId?: string
+
+  @Field({ nullable: true, description: 'Persisted ChatMessage id of the user input.' })
+  userMessageId?: string
+
+  @Field({ nullable: true, description: 'Persisted ChatMessage id of the AI reply.' })
+  assistantMessageId?: string
+
+  @Field({ nullable: true, description: 'Persisted PatchEntry id (when patch was generated).' })
+  patchId?: string
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Tool usages collected during agentic loop — sequence of {name, arguments, result, kind}. UI fold-able box for transparency / debug.'
+  })
+  toolUsages?: any
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Ephemeral scene actions (selection/view/mode) — sequence of BoardActionOp. Applied via board-action-execute event on the host. Distinct from `patch` which carries persistent model changes.'
+  })
+  actions?: any
+}
+
+@Resolver()
+export class BoardAIChatResolver {
+  /**
+   * NOTE: 일부러 @Directive('@transaction') 사용하지 않는다.
+   * LLM 호출은 수 초~수십 초 — 트랜잭션 안에서 호출하면 SQLite write lock 을
+   * 그 시간 동안 보유 → 다른 작업 (cache 정리 등) 과 SQLITE_BUSY 충돌.
+   * 따라서 DB 쓰기를 LLM 호출 전후의 짧은 단위로 나누고 각각 auto-commit.
+   * 데이터 일관성: 채팅 이력은 부분 누락보다 부분 보존이 안전 (대화 컨텍스트).
+   */
+  @Mutation(() => BoardAIChatOutput, {
+    description: 'AI 주도 보드 모델링 — 자연어 채팅으로 보드 생성·구조편집·스타일링. sessionId 로 영속 컨텍스트.'
+  })
+  @Directive('@privilege(category: "board-ai", privilege: "mutation")')
+  async boardAIChat(
+    @Arg('input') input: BoardAIChatInput,
+    @Ctx() context: ResolverContext
+  ): Promise<BoardAIChatOutput> {
+    const base = resolveAIClient()
+    if (!base) {
+      throw new Error(
+        'No AI client configured. Set config.aiClient = { provider: "anthropic" | "gemini", model, apiKey } or call setDefaultAIClient(...).'
+      )
+    }
+
+    const { domain, user } = context.state
+    const sessionRepo = getRepository(ChatSession)
+    const messageRepo = getRepository(ChatMessage)
+    const patchRepo = getRepository(PatchEntry)
+
+    // ── Phase A: LLM 호출 전 짧은 DB 쓰기 ─────────────────────────
+    let session: ChatSession | undefined
+    if (input.sessionId) {
+      const found = await sessionRepo.findOneBy({ id: input.sessionId, domain: { id: domain.id } })
+      if (!found) throw new Error(`ChatSession ${input.sessionId} not found`)
+      session = found
+    }
+
+    const lastUserMsg = input.messages[input.messages.length - 1]
+    let userMessageId: string | undefined
+    if (session && lastUserMsg && lastUserMsg.role === 'user') {
+      // popup pick 의 refid 를 #token{refid:N} inline marker 로 content 에 박아 저장.
+      // 단일 source-of-truth — 별도 컬럼 없이 content 안에서 token-refid 매핑 보존.
+      const enriched = injectMentionRefids(lastUserMsg.content, input.mentions)
+      // parentMessage = 이 세션의 직전 메시지 (보통 assistant / system / 또는 첫 turn 이면 null).
+      // tree 구조 인프라 — branching (regenerate / 사용자별 분기) 는 같은 부모 child 로.
+      const previousLast = await messageRepo.findOne({
+        where: { session: { id: session.id } as any },
+        order: { createdAt: 'DESC' }
+      })
+      const saved = await messageRepo.save({
+        session: { id: session.id } as any,
+        role: 'user',
+        content: enriched,
+        creator: user,
+        updater: user,
+        parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
+      })
+      userMessageId = saved.id
+
+      // C4: 사용자 메시지를 같은 세션 구독자에게 방송 (그룹챗 실시간). best-effort.
+      // 자기 발신 에코는 클라이언트가 message.id 로 dedup.
+      publishChatMessage({ domainId: domain.id, sessionId: session.id, message: saved })
+
+      // C4: @user 멘션 → 세션 참여자(member) 자동 등록 (초대). best-effort — 실패해도 chat 흐름 무영향.
+      // enriched content 의 {userId:UUID} 마커에서 추출 → 기존 참여자/자기 제외한 신규만 member 로 등록.
+      try {
+        await this._inviteMentionedUsers(enriched, session.id!, domain.id, user, session.boardId, (context.state as any).notify)
+      } catch {
+        /* 초대 실패는 대화를 막지 않는다 */
+      }
+    }
+
+    // ── Phase B: LLM 호출 (DB 잠금 없음, 오래 걸려도 OK) ───────────
+    const assistant = new DefaultBoardAIAssistant(base, {
+      scopes: input.scopes,
+      knownTypes: input.knownTypes,
+      categories: input.categories as ComponentCategory[] | undefined
+    })
+
+    // 영속된 메시지에는 #token{refid:N} inline marker 가 박혀 있을 수 있음. LLM 한테는
+     // 깨끗한 텍스트만 보여 주의 분산 방지 + 토큰 낭비 방지.
+    const llmMessages: LLMMessage[] = input.messages.map(m => ({
+      role: m.role === 'assistant' ? 'assistant' : 'user',
+      content: stripMentionRefids(m.content)
+    }))
+
+    const r = await assistant.chat(llmMessages, input.currentBoard ?? undefined, {
+      scopes: input.scopes,
+      knownTypes: input.knownTypes,
+      categories: input.categories as ComponentCategory[] | undefined,
+      selectedRefids: input.selectedRefids,
+      mentionPicks: input.mentions,
+      componentSchemas: Array.isArray(input.componentSchemas) ? input.componentSchemas : undefined,
+      model: input.model,
+      temperature: input.temperature ?? undefined,
+      maxTokens: input.maxTokens ?? undefined,
+      // 외부 도메인 (board-import 등) 의 read/external tool builder 가 server-side
+      // 의존성 (도메인 / 유저 / 트랜잭션) 을 사용할 수 있도록 ResolverContext.state 전달.
+      // board-ai 코어 자체는 이 값을 알지 않고 dispatch 단계에서 closure 로만 흘림.
+      toolCallContext: context.state
+    })
+
+    // ── Phase C: LLM 호출 후 짧은 DB 쓰기 ─────────────────────────
+    let assistantMessageId: string | undefined
+    let patchId: string | undefined
+    if (session) {
+      let patchEntry: PatchEntry | undefined
+      if (r.patch) {
+        patchEntry = await patchRepo.save({
+          session: { id: session.id } as any,
+          source: 'ai',
+          ops: JSON.stringify(r.patch.ops),
+          summary: r.patch.summary,
+          confidence: r.patch.confidence,
+          reverted: false
+        })
+        patchId = patchEntry.id
+        // C1: 같은 board 구독자에게 방송 (실시간 공동편집 spine). best-effort.
+        publishBoardPatch({ domainId: domain.id, boardId: session.boardId, patch: patchEntry })
+      }
+
+      // AI 응답의 #token 들을 currentBoard 에 대해 resolve 한 뒤 inline marker 로 박음.
+      // patch 로 새로 만든 컴포넌트는 input.currentBoard 에 없으므로 marker 없이 저장 →
+      // 클릭 시 runtime fallback 으로 해석 (그때는 patch 적용 후라 scene 에 존재).
+      const enrichedReply = injectAiMentionRefids(r.reply, input.currentBoard ?? null)
+
+      const aiMsg = await messageRepo.save({
+        session: { id: session.id } as any,
+        role: 'assistant',
+        content: enrichedReply,
+        relatedPatchId: patchEntry?.id,
+        toolUsages: r.toolUsages && r.toolUsages.length > 0 ? JSON.stringify(r.toolUsages) : undefined,
+        // assistant 메시지의 creator = 이 응답을 트리거한 user (= 직전 user 메시지의 작성자).
+        // 같은 turn 으로 묶임 → 향후 사용자별 필터에서 user/assistant 가 함께 따라옴.
+        creator: user,
+        updater: user,
+        // parentMessage = 이 응답이 답하는 user 메시지. regenerate 시 같은 user 메시지를
+        // 부모로 하는 형제 assistant 들이 생기면 자연스럽게 branching tree.
+        parentMessage: userMessageId ? ({ id: userMessageId } as any) : undefined
+      })
+      assistantMessageId = aiMsg.id
+
+      // C4: AI 응답도 같은 세션 구독자에게 방송 (트리거한 본인 포함 — id dedup). best-effort.
+      publishChatMessage({ domainId: domain.id, sessionId: session.id, message: aiMsg })
+
+      await sessionRepo.update(session.id, {
+        aiClientId: base.id,
+        updater: user
+      })
+    }
+
+    return {
+      reply: r.reply,
+      patch: r.patch ?? null,
+      followUp: r.followUp ?? null,
+      clientId: base.id,
+      sessionId: session?.id,
+      userMessageId,
+      assistantMessageId,
+      patchId,
+      toolUsages: r.toolUsages ?? null,
+      actions: r.actions && r.actions.length > 0 ? r.actions : null
+    }
+  }
+
+  /**
+   * C4: 메시지에 @멘션된 사용자를 세션 참여자(member)로 자동 등록 — 초대.
+   * enriched content 의 {userId:UUID} 마커에서 추출 → 기존 참여자·자기 제외한 신규만 등록.
+   * 소프트삭제(deletedAt)된 과거 참여자는 다시 살린다(재초대). 신규 등록 후 협업 초대 알림 발송(C4b-2, best-effort).
+   */
+  private async _inviteMentionedUsers(
+    content: string,
+    sessionId: string,
+    domainId: string,
+    inviter: any,
+    boardId?: string,
+    notify?: (arg: any) => Promise<void>
+  ): Promise<void> {
+    const mentioned = extractMentionUserIds(content)
+    if (mentioned.length === 0) return
+
+    const repo = getRepository(ChatSessionParticipant)
+    const existing = await repo.find({
+      where: { session: { id: sessionId } as any, domain: { id: domainId } as any },
+      withDeleted: true
+    })
+    const activeIds = existing.filter(p => !p.deletedAt).map(p => p.userId!).filter(Boolean)
+    const fresh = newParticipantUserIds(mentioned, activeIds, inviter?.id)
+    if (fresh.length === 0) return
+
+    for (const userId of fresh) {
+      // 과거에 나갔던(soft-deleted) 참여자면 되살리고, 아니면 새로 등록.
+      const prior = existing.find(p => p.userId === userId && p.deletedAt)
+      if (prior) {
+        await repo.update(prior.id!, { deletedAt: null as any, role: 'member', updater: inviter } as any)
+      } else {
+        await repo.save({
+          domain: { id: domainId } as any,
+          session: { id: sessionId } as any,
+          user: { id: userId } as any,
+          role: 'member',
+          creator: inviter,
+          updater: inviter
+        } as any)
+      }
+    }
+
+    // C4b-2: 초대 알림 — notification 모듈의 기존 발송 메커니즘 재사용(중복 구현 금지).
+    // context.state.notify 는 notification-middleware 가 전역 주입(FCM/pubsub). duck-typed →
+    // board-ai 에 의존성 추가 없이 런타임 호출. 미로드 환경이면 undefined → graceful skip.
+    this._notifyInvited(notify, fresh, boardId, inviter)
+  }
+
+  /** 초대된 사용자들에게 협업 초대 알림 발송 (best-effort, capability 있을 때만). */
+  private _notifyInvited(
+    notify: ((arg: any) => Promise<void>) | undefined,
+    userIds: string[],
+    boardId: string | undefined,
+    inviter: any
+  ): void {
+    if (typeof notify !== 'function') return
+    const payload = buildInviteNotification(userIds, boardId, inviter)
+    if (!payload) return
+    Promise.resolve(notify(payload)).catch(() => {
+      /* 알림 실패는 초대·대화를 막지 않는다 */
+    })
+  }
+}
+
+function resolveAIClient(): AIClient | undefined {
+  const existing = getDefaultAIClient()
+  if (existing) return existing
+  const cfg = config.get('aiClient', null) as any
+  if (cfg && cfg.provider) {
+    return createAIClient(cfg)
+  }
+  return undefined
+}

package/server/service/catalog-resolver.test.ts

@@ -0,0 +1,137 @@
+/**
+ * catalog-resolver.ts 단위 테스트.
+ *
+ * 핵심 보호:
+ *   - @name → 'name (kind)' 정확 변환 (prefab / palette / layout 각각)
+ *   - 다중 kind 매치 시 'name (prefab and palette)' 형태
+ *   - 매칭 실패 → 원문 그대로
+ *   - 멀티 토큰 위치 보존
+ *   - 단어 중간 @ (email-like 'user@host') 는 어떻게 — 의도적 단순 처리
+ */
+import {
+  resolveCatalogMentions,
+  findCatalogMentions,
+  lookupCatalogKinds
+} from './catalog-resolver'
+
+describe('lookupCatalogKinds', () => {
+  test('default prefab 3종 인식', () => {
+    expect(lookupCatalogKinds('monitor-card')).toEqual(['prefab'])
+    expect(lookupCatalogKinds('gauge-panel')).toEqual(['prefab'])
+    expect(lookupCatalogKinds('stat-tile')).toEqual(['prefab'])
+  })
+
+  test('default palette 7종 인식', () => {
+    expect(lookupCatalogKinds('industrial-steel')).toEqual(['palette'])
+    expect(lookupCatalogKinds('financial-trader')).toEqual(['palette'])
+    expect(lookupCatalogKinds('neon-cyberpunk')).toEqual(['palette'])
+  })
+
+  test('default layout 6종 인식', () => {
+    expect(lookupCatalogKinds('kpi-row')).toEqual(['layout'])
+    expect(lookupCatalogKinds('3x3-grid')).toEqual(['layout'])
+    expect(lookupCatalogKinds('t-shape-command')).toEqual(['layout'])
+  })
+
+  test('알 수 없는 이름 → []', () => {
+    expect(lookupCatalogKinds('no-such-thing')).toEqual([])
+  })
+
+  test('대소문자 구분 — 정확 매칭만', () => {
+    expect(lookupCatalogKinds('Monitor-Card')).toEqual([])
+    expect(lookupCatalogKinds('INDUSTRIAL-STEEL')).toEqual([])
+  })
+})
+
+describe('resolveCatalogMentions — 단일 매칭', () => {
+  test('prefab', () => {
+    expect(resolveCatalogMentions('@monitor-card 3개 추가')).toBe(
+      'monitor-card (prefab) 3개 추가'
+    )
+  })
+
+  test('palette', () => {
+    expect(resolveCatalogMentions('@industrial-steel 팔레트')).toBe(
+      'industrial-steel (palette) 팔레트'
+    )
+  })
+
+  test('layout', () => {
+    expect(resolveCatalogMentions('@kpi-row 으로 정렬')).toBe(
+      'kpi-row (layout) 으로 정렬'
+    )
+  })
+})
+
+describe('resolveCatalogMentions — 매칭 실패', () => {
+  test('알 수 없는 이름 → 원문 보존', () => {
+    expect(resolveCatalogMentions('@unknown-thing 어쩌고')).toBe(
+      '@unknown-thing 어쩌고'
+    )
+  })
+
+  test('빈 텍스트 안전', () => {
+    expect(resolveCatalogMentions('')).toBe('')
+  })
+
+  test('@ 만 있고 token 없으면 변환 안 함', () => {
+    expect(resolveCatalogMentions('@ alone')).toBe('@ alone')
+  })
+
+  test('email-like (user@host) 도 token 매칭 — 카탈로그에 없으면 그대로', () => {
+    // @host 가 카탈로그 매칭이면 변환됨. 이 테스트의 'host' 는 카탈로그에 없음.
+    expect(resolveCatalogMentions('contact me at user@host')).toBe(
+      'contact me at user@host'
+    )
+  })
+})
+
+describe('resolveCatalogMentions — 멀티 토큰', () => {
+  test('서로 다른 카탈로그의 두 토큰', () => {
+    expect(
+      resolveCatalogMentions('@monitor-card 를 @industrial-steel 로')
+    ).toBe('monitor-card (prefab) 를 industrial-steel (palette) 로')
+  })
+
+  test('일부만 매칭 — 나머지는 원문', () => {
+    expect(resolveCatalogMentions('@monitor-card and @no-such')).toBe(
+      'monitor-card (prefab) and @no-such'
+    )
+  })
+
+  test('3종 카탈로그 한 메시지에', () => {
+    expect(
+      resolveCatalogMentions('@kpi-row 에 @monitor-card 3개 + @neon-cyberpunk')
+    ).toBe(
+      'kpi-row (layout) 에 monitor-card (prefab) 3개 + neon-cyberpunk (palette)'
+    )
+  })
+})
+
+describe('resolveCatalogMentions — 위치 보존 (뒤에서 앞으로 치환)', () => {
+  test('첫 번째 토큰 매칭, 두 번째 매칭 실패 — 인덱스 어긋남 없이 정확', () => {
+    const r = resolveCatalogMentions('@stat-tile 와 @notmatch')
+    expect(r).toBe('stat-tile (prefab) 와 @notmatch')
+  })
+
+  test('치환 결과가 원본보다 길어져도 후속 토큰 위치 정확', () => {
+    // 원본 길이가 변해도 backward iteration 으로 안전
+    const r = resolveCatalogMentions('a @stat-tile b @gauge-panel c')
+    expect(r).toBe('a stat-tile (prefab) b gauge-panel (prefab) c')
+  })
+})
+
+describe('findCatalogMentions — UI / 디버그용', () => {
+  test('모든 매칭 결과 (성공 + 실패) 반환', () => {
+    const r = findCatalogMentions('@monitor-card @no-such @industrial-steel')
+    expect(r).toEqual([
+      { token: 'monitor-card', kinds: ['prefab'] },
+      { token: 'no-such', kinds: [] },
+      { token: 'industrial-steel', kinds: ['palette'] }
+    ])
+  })
+
+  test('빈 텍스트 → []', () => {
+    expect(findCatalogMentions('')).toEqual([])
+  })
+})

package/server/service/catalog-resolver.ts

@@ -0,0 +1,102 @@
+/**
+ * `@name` 카탈로그 멘션 → kind disambiguation.
+ *
+ * Phase 1A 의 mention-resolver (#name → 'name (refid 35)') 와 같은 패턴을
+ * 카탈로그 (prefab / color palette / layout template) 식별자에 적용.
+ *
+ *   "@monitor-card 3개 추가"
+ *     → "monitor-card (prefab) 3개 추가"
+ *
+ *   "@industrial-steel 팔레트로 통일"
+ *     → "industrial-steel (palette) 팔레트로 통일"
+ *
+ * 다중 kind 매치 (이름이 prefab + palette 둘 다인 희귀 케이스):
+ *     → "name (prefab and palette)"
+ *
+ * 매칭 0 — 원문 보존 (AI 가 자연어로 폴백).
+ *
+ * Token 정의: `@` 뒤의 공백/`@` 이 아닌 모든 글자. 정규식 /@([^\s@]+)/g.
+ *
+ * 의도: AI 가 이름을 자유 작곡 / hallucinate 하지 않고 정확한 카탈로그 식별자를
+ * 사용하도록 호출자가 명시한 의도를 server-side 에서 보강.
+ */
+import { listBoardPrefabs } from './prefab-registry'
+import { listColorPaletteNames, listLayoutTemplateNames } from './assistant'
+
+export type CatalogKind = 'prefab' | 'palette' | 'layout'
+
+const CATALOG_PATTERN = /@([^\s@]+)/g
+
+/**
+ * 텍스트의 `@token` 들을 카탈로그와 매칭해 LLM 친화 형태로 변환.
+ */
+export function resolveCatalogMentions(text: string): string {
+  if (!text || typeof text !== 'string') return text
+  const matches = collectCatalogMatches(text)
+  if (matches.length === 0) return text
+
+  let out = text
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const m = matches[i]
+    if (m.kinds.length === 0) continue // 매칭 실패 — 그대로
+    const replacement = formatCatalogReplacement(m.token, m.kinds)
+    out = out.slice(0, m.start) + replacement + out.slice(m.end)
+  }
+  return out
+}
+
+interface CatalogMatch {
+  token: string
+  start: number
+  end: number
+  kinds: CatalogKind[]
+}
+
+function collectCatalogMatches(text: string): CatalogMatch[] {
+  const matches: CatalogMatch[] = []
+  const pattern = new RegExp(CATALOG_PATTERN.source, 'g')
+  let m: RegExpExecArray | null
+  while ((m = pattern.exec(text)) !== null) {
+    const token = m[1]
+    const kinds = lookupCatalogKinds(token)
+    matches.push({
+      token,
+      start: m.index,
+      end: m.index + m[0].length,
+      kinds
+    })
+  }
+  return matches
+}
+
+/**
+ * Token 의 매칭 kind 목록 (case-sensitive — 카탈로그 식별자는 정확 매칭).
+ *
+ * 같은 이름이 여러 카탈로그에 존재해도 모두 반환. UI 가 disambiguation 안내.
+ */
+export function lookupCatalogKinds(token: string): CatalogKind[] {
+  const kinds: CatalogKind[] = []
+  const prefabs = listBoardPrefabs()
+  if (prefabs.some(p => p.name === token)) kinds.push('prefab')
+  if (listColorPaletteNames().includes(token)) kinds.push('palette')
+  if (listLayoutTemplateNames().includes(token)) kinds.push('layout')
+  return kinds
+}
+
+function formatCatalogReplacement(token: string, kinds: CatalogKind[]): string {
+  if (kinds.length === 1) return `${token} (${kinds[0]})`
+  return `${token} (${kinds.join(' and ')})`
+}
+
+/**
+ * 텍스트의 모든 `@token` 매칭 결과 — UI / 디버그용.
+ */
+export function findCatalogMentions(
+  text: string
+): Array<{ token: string; kinds: CatalogKind[] }> {
+  if (!text || typeof text !== 'string') return []
+  return collectCatalogMatches(text).map(m => ({
+    token: m.token,
+    kinds: m.kinds
+  }))
+}