@things-factory/ai-client-base 10.0.0-beta.64 → 10.0.0-beta.72

package/server/service/tool-registry/registry.test.ts

@@ -0,0 +1,185 @@
+/**
+ * ToolCategoryRegistry — 단위 테스트.
+ *
+ * plugin point 의 회귀 방지:
+ *   - 등록 / 조회 / 평면 합집합 / kind 분류 / 충돌 / clear
+ *   - 카테고리 간 격리 (한 카테고리 변경이 다른 것에 영향 X)
+ *   - 빈 등록 시 baseline (assistant 의 hardcoded tool 만 동작)
+ */
+import {
+  registerToolCategory,
+  getToolCategories,
+  getAllToolSpecs,
+  findToolSpec,
+  getToolKind,
+  hasTool,
+  getCategorySpecs,
+  clearToolRegistry
+} from './registry'
+import type { ToolCategory, ToolSpec } from './types'
+
+// 테스트 간 격리
+afterEach(() => {
+  clearToolRegistry()
+})
+
+// 헬퍼 — 카테고리 fixture
+function makeCategory(name: string, specs: Partial<ToolSpec>[]): ToolCategory {
+  return {
+    name,
+    specs: specs.map(s => ({
+      kind: 'read' as const,
+      name: 'unnamed',
+      description: 'desc',
+      schema: {},
+      builder: () => ({}),
+      ...s
+    })) as ToolSpec[]
+  }
+}
+
+// ── 기본 등록 / 조회 ─────────────────────────────────────────────────
+
+describe('registry — 기본 등록/조회', () => {
+  test('빈 registry 는 빈 결과', () => {
+    expect(getToolCategories()).toEqual([])
+    expect(getAllToolSpecs()).toEqual([])
+    expect(findToolSpec('any')).toBeUndefined()
+    expect(getToolKind('any')).toBeUndefined()
+    expect(hasTool('any')).toBe(false)
+  })
+
+  test('카테고리 등록 후 조회', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 't1' }, { name: 't2' }]))
+    expect(getToolCategories()).toHaveLength(1)
+    expect(getToolCategories()[0].name).toBe('cat1')
+    expect(getCategorySpecs('cat1')).toHaveLength(2)
+  })
+
+  test('getAllToolSpecs 는 카테고리 간 평면 합집합', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 't1' }]))
+    registerToolCategory(makeCategory('cat2', [{ name: 't2' }, { name: 't3' }]))
+    expect(getAllToolSpecs()).toHaveLength(3)
+    expect(getAllToolSpecs().map(s => s.name)).toEqual(['t1', 't2', 't3'])
+  })
+
+  test('findToolSpec 은 카테고리 무관 검색', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 'foo' }]))
+    registerToolCategory(makeCategory('cat2', [{ name: 'bar' }]))
+    expect(findToolSpec('foo')?.name).toBe('foo')
+    expect(findToolSpec('bar')?.name).toBe('bar')
+    expect(findToolSpec('baz')).toBeUndefined()
+  })
+
+  test('hasTool 은 등록 여부 boolean', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 'foo' }]))
+    expect(hasTool('foo')).toBe(true)
+    expect(hasTool('bar')).toBe(false)
+  })
+})
+
+// ── kind 분류 ────────────────────────────────────────────────────────
+
+describe('registry — kind 분류', () => {
+  test("getToolKind 는 spec.kind 그대로 반환", () => {
+    registerToolCategory(
+      makeCategory('mixed', [
+        { name: 'r1', kind: 'read' },
+        { name: 'w1', kind: 'write' },
+        { name: 'a1', kind: 'action' },
+        { name: 'e1', kind: 'external' }
+      ])
+    )
+    expect(getToolKind('r1')).toBe('read')
+    expect(getToolKind('w1')).toBe('write')
+    expect(getToolKind('a1')).toBe('action')
+    expect(getToolKind('e1')).toBe('external')
+    expect(getToolKind('x1')).toBeUndefined()
+  })
+})
+
+// ── 충돌 / 격리 ──────────────────────────────────────────────────────
+
+describe('registry — 충돌 / 격리', () => {
+  test('서로 다른 카테고리에 같은 tool name 등록 거부 (throw)', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 'duplicate' }]))
+    expect(() =>
+      registerToolCategory(makeCategory('cat2', [{ name: 'duplicate' }]))
+    ).toThrow(/already registered in category/)
+  })
+
+  test('같은 카테고리 재등록은 덮어쓰기 (warn 출력)', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    registerToolCategory(makeCategory('cat1', [{ name: 'old' }]))
+    registerToolCategory(makeCategory('cat1', [{ name: 'new1' }, { name: 'new2' }]))
+    expect(warnSpy).toHaveBeenCalled()
+    expect(getCategorySpecs('cat1').map(s => s.name)).toEqual(['new1', 'new2'])
+    warnSpy.mockRestore()
+  })
+
+  test('한 카테고리 변경이 다른 카테고리에 영향 X', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 't1' }]))
+    registerToolCategory(makeCategory('cat2', [{ name: 't2' }]))
+    // cat1 재등록 — cat2 는 보존되어야
+    registerToolCategory(makeCategory('cat1', [{ name: 't1-new' }]))
+    expect(getCategorySpecs('cat1').map(s => s.name)).toEqual(['t1-new'])
+    expect(getCategorySpecs('cat2').map(s => s.name)).toEqual(['t2'])
+  })
+
+  test('clearToolRegistry 는 모든 등록 해제', () => {
+    registerToolCategory(makeCategory('cat1', [{ name: 't1' }]))
+    registerToolCategory(makeCategory('cat2', [{ name: 't2' }]))
+    clearToolRegistry()
+    expect(getToolCategories()).toEqual([])
+    expect(getAllToolSpecs()).toEqual([])
+  })
+})
+
+// ── builder 호출 — 등록만 하고 실제 dispatch 는 assistant 측 ──────────
+
+describe('registry — spec 보존', () => {
+  test('등록한 builder 가 spec 안에 그대로 보존', () => {
+    const builder = jest.fn(() => ({ ok: true }))
+    registerToolCategory({
+      name: 'cat1',
+      specs: [
+        {
+          kind: 'read',
+          name: 'mybuilder',
+          description: 'desc',
+          schema: {},
+          builder
+        } as ToolSpec
+      ]
+    })
+    const spec = findToolSpec('mybuilder')
+    expect(spec).toBeDefined()
+    expect(spec!.kind).toBe('read')
+    // ToolSpec 의 builder 는 카테고리 별 다른 시그니처지만 본 테스트는 단순 호출
+    if (spec!.kind === 'read') {
+      const r = (spec.builder as any)({}, {})
+      expect(r).toEqual({ ok: true })
+      expect(builder).toHaveBeenCalled()
+    }
+  })
+
+  test('description / themeNote / schema 보존', () => {
+    registerToolCategory({
+      name: 'cat1',
+      specs: [
+        {
+          kind: 'write',
+          name: 't1',
+          description: 'main desc',
+          themeNote: '⚠ note',
+          schema: { type: 'object' },
+          builder: () => null
+        } as ToolSpec
+      ]
+    })
+    const spec = findToolSpec('t1')
+    expect(spec?.description).toBe('main desc')
+    expect(spec?.themeNote).toBe('⚠ note')
+    expect(spec?.schema).toEqual({ type: 'object' })
+  })
+})

package/server/service/tool-registry/registry.ts

@@ -0,0 +1,121 @@
+/**
+ * ToolCategoryRegistry — 외부 도메인 패키지가 LLM tool category 를 동적 등록하는 점.
+ *
+ * 사용 패턴 (외부 패키지의 server bootstrap):
+ *   ```ts
+ *   import { registerToolCategory } from '@things-factory/board-ai'
+ *
+ *   registerToolCategory({
+ *     name: 'board-import',
+ *     specs: [
+ *       { kind: 'external', name: 'importBoardAsync', schema: {...}, builder: ... },
+ *       { kind: 'read',     name: 'getImportSession', schema: {...}, builder: ... },
+ *       ...
+ *     ]
+ *   })
+ *   ```
+ *
+ * board-ai assistant.ts 의 buildBoardEditTools / dispatch / isWriteTool 등이
+ * 본 registry 에서 자동 도출.
+ *
+ * 정책:
+ *   - 카테고리 이름은 unique. 같은 이름으로 재등록하면 덮어쓰기 (외부 패키지의
+ *     hot-reload / dev 환경 대응). console.warn 으로 알림.
+ *   - tool name 은 카테고리 간 통틀어 unique. 충돌 시 등록 거부 + 명확한 에러
+ *     (LLM dispatch 가 모호해지지 않도록).
+ *   - clear() 는 테스트 전용. 운영 환경에서 호출 금지.
+ */
+import type { ToolCategory, ToolSpec } from './types'
+
+const categories: Map<string, ToolCategory> = new Map()
+
+/**
+ * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
+ */
+export function registerToolCategory(category: ToolCategory): void {
+  if (categories.has(category.name)) {
+    console.warn(
+      `[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
+        `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`
+    )
+  }
+
+  // tool name 충돌 검사 — 다른 카테고리에 같은 name 있으면 거부
+  const newNames = new Set(category.specs.map(s => s.name))
+  for (const [otherName, other] of categories) {
+    if (otherName === category.name) continue // 같은 카테고리 재등록은 덮어쓰기 OK
+    for (const spec of other.specs) {
+      if (newNames.has(spec.name)) {
+        throw new Error(
+          `[board-ai/tool-registry] tool name '${spec.name}' already registered in category ` +
+            `'${otherName}', cannot register in '${category.name}'. tool names must be globally unique.`
+        )
+      }
+    }
+  }
+
+  categories.set(category.name, category)
+}
+
+/**
+ * 등록된 모든 카테고리 (등록 순서 보존). 외부에서 불변 read-only 로 사용.
+ */
+export function getToolCategories(): ReadonlyArray<ToolCategory> {
+  return Array.from(categories.values())
+}
+
+/**
+ * 등록된 모든 tool spec 의 평면 view. assistant.ts 의 buildBoardEditTools 가
+ * LLM tool 정의 합집합으로 사용.
+ */
+export function getAllToolSpecs(): ReadonlyArray<ToolSpec> {
+  const out: ToolSpec[] = []
+  for (const cat of categories.values()) {
+    for (const spec of cat.specs) out.push(spec)
+  }
+  return out
+}
+
+/**
+ * tool name 으로 spec 검색. 없으면 undefined.
+ */
+export function findToolSpec(name: string): ToolSpec | undefined {
+  for (const cat of categories.values()) {
+    const spec = cat.specs.find(s => s.name === name)
+    if (spec) return spec
+  }
+  return undefined
+}
+
+/**
+ * tool name 의 카테고리 (read/write/action/external). 미등록 tool 은 undefined.
+ * assistant.ts 의 isReadTool / isWriteTool / isActionTool 이 이 함수에 위임할 수 있다.
+ */
+export function getToolKind(name: string): ToolSpec['kind'] | undefined {
+  return findToolSpec(name)?.kind
+}
+
+/**
+ * 등록된 tool 인지. dispatch path 가 hardcoded set 와 registry 양쪽 fallback 시 사용.
+ */
+export function hasTool(name: string): boolean {
+  return findToolSpec(name) !== undefined
+}
+
+/**
+ * 카테고리 이름으로 spec 만 추출.
+ */
+export function getCategorySpecs(categoryName: string): ReadonlyArray<ToolSpec> {
+  return categories.get(categoryName)?.specs ?? []
+}
+
+/**
+ * 테스트 전용 — 모든 등록 해제. 운영 환경에서 호출 금지.
+ *
+ * jest 의 setupFilesAfterEach 또는 명시적 afterEach 에서 호출해 테스트 간 격리.
+ * 실제로 STYLING_TOOLS 는 board-ai 자체 부트스트랩에서 다시 등록되므로 clear 후
+ * 명시 register 가 필요한 것은 동적 카테고리 (board-import 등) 뿐.
+ */
+export function clearToolRegistry(): void {
+  categories.clear()
+}

package/server/service/tool-registry/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Tool Registry — board-ai 의 LLM tool 노출 plugin point.
+ *
+ * 동기:
+ *   기존엔 board-ai 가 자기 도메인 (board edit) tool 들만 hardcoded 정의했고, styling
+ *   영역만 STYLING_TOOLS registry 로 분리되어 있었다. 외부 도메인 패키지 (board-import,
+ *   fmsim 등) 가 자기 tool 을 LLM 에 노출하려면 board-ai 자체를 fork/수정해야 했다.
+ *
+ *   본 registry 는 외부 패키지가 server bootstrap 시 자기 tool category 를 등록하면
+ *   assistant.ts 의 buildBoardEditTools / dispatch / isWriteTool 등이 자동으로 통합
+ *   하도록 한다. styling-tools 의 single-source-of-truth 패턴을 일반화한 형태.
+ *
+ * 설계 원칙:
+ *   - **카테고리별 builder 시그니처 다양성을 통합**: read 는 (args, ctx) → any,
+ *     write 는 (args, components) → BoardEditOp[], action 은 (args) → BoardActionOp.
+ *     하나의 ToolSpec 에 모든 시그니처를 union 으로 담지 않고, 카테고리에 맞는
+ *     builder 만 채우면 되도록 카테고리별 sub-interface 분리.
+ *   - **kind 필드로 자가 분류**: registry 가 isReadTool / isWriteTool 자동 도출.
+ *     hardcoded set 동기화 누락 위험 제거.
+ *   - **점진 마이그레이션**: 기존 STYLING_TOOLS 가 본 registry 의 첫 사용자.
+ *     점진적으로 다른 hardcoded tool 들 (addComponent / alignComponents 등) 도
+ *     같은 registry 로 흡수 가능. 한 단계씩 byte-단위 동등성 단위 테스트 보장.
+ */
+// 본 registry 는 LLM tool 노출 plugin point 에 한정되므로 도메인 type (BoardEditOp,
+// BoardActionOp 등) 은 알지 않는다. builder return 은 unknown 으로 두고, 카테고리
+// dispatcher (board-ai 의 toolCallToBoardEditOp / toolCallToBoardActionOp 등) 가 자기
+// 도메인 type 으로 좁힌다. 사용자가 ToolSpec<TWrite, TAction> generic 까지 정밀화하면
+// 좋겠지만, 11~50 개 spec 마다 type 인자 전파가 부담이라 unknown 으로 합의.
+
+// ── 카테고리별 builder 시그니처 ──────────────────────────────────────
+
+/**
+ * Read tool — server 측 즉시 실행, 결과를 LLM 에 회신. board model 변경 X.
+ * 예: getSelection / findComponents / importSession (query)
+ */
+export type ReadToolBuilder = (
+  args: any,
+  context: ReadToolContext
+) => any | Promise<any>
+
+export interface ReadToolContext {
+  /** 현재 board model — 일부 read tool 이 사용 (getSelection 등). */
+  board?: any
+  /** 현재 선택된 refids. */
+  selectedRefids?: number[]
+  /** 호출자 도메인 / 사용자 / 트랜잭션. registry 외부에서 주입. */
+  state?: any
+  /** 이외 주입은 카테고리별로 자유. tool 등록자가 type 좁힐 수 있도록 unknown 으로 보존. */
+  [k: string]: any
+}
+
+/**
+ * Write tool — domain edit op 발생. host 가 patch 적용 후 영속화.
+ * 예: board-ai 의 addComponent / setFill / modifyBoard.
+ *
+ * builder 의 return type 은 unknown 으로 둔다 — 도메인별 dispatcher (예: board-ai 의
+ * toolCallToBoardEditOp) 가 자기 EditOp[] 로 cast. ops/errors wrapper 형태도 동일 의미.
+ */
+export type WriteToolBuilder = (
+  args: any,
+  context: WriteToolContext
+) => any[] | { ops: any[]; errors?: string[] } | null
+
+export interface WriteToolContext {
+  components?: ReadonlyArray<any>
+  [k: string]: any
+}
+
+/**
+ * Action tool — ephemeral scene 조작 (select / center / fit / sceneMode).
+ * board model 변경 X, undo 영향 X. host 가 별도 channel 로 적용.
+ *
+ * return type 은 unknown — 도메인별 dispatcher (예: board-ai 의 toolCallToBoardActionOp)
+ * 가 자기 BoardActionOp 으로 cast.
+ */
+export type ActionToolBuilder = (args: any) => any | null
+
+/**
+ * External-call tool — 외부 service / mutation / RPC 호출. 직접 board model 영향 X
+ * (별도 entity 변경은 가능). 결과는 LLM 에 회신.
+ *
+ * board-import 의 importBoardAsync / materializeImportSession 같이 board-ai 외부
+ * 도메인을 호출하는 tool 의 카테고리.
+ */
+export type ExternalToolBuilder = (
+  args: any,
+  context: ExternalToolContext
+) => any | Promise<any>
+
+export interface ExternalToolContext {
+  state?: any
+  [k: string]: any
+}
+
+// ── ToolSpec — 카테고리별 변형 ──────────────────────────────────────
+
+/**
+ * 모든 ToolSpec 공통 메타데이터.
+ */
+export interface ToolSpecBase {
+  /** AIToolCall.name 매칭. 전 카테고리 통틀어 unique. */
+  name: string
+  /** 기능 설명 (영문 위주). LLM 의 tool description 으로 사용. */
+  description: string
+  /**
+   * 선택 — 정책 / 테마 가이드 단문. tool description 끝에 자동 부착.
+   * styling-tools 의 themeNote 와 동일 의미. 기타 카테고리도 사용 가능.
+   */
+  themeNote?: string
+  /** JSON Schema for parameters — LLM tool schema 에 그대로 노출. */
+  schema: any
+}
+
+export interface ReadToolSpec extends ToolSpecBase {
+  kind: 'read'
+  builder: ReadToolBuilder
+}
+
+export interface WriteToolSpec extends ToolSpecBase {
+  kind: 'write'
+  builder: WriteToolBuilder
+}
+
+export interface ActionToolSpec extends ToolSpecBase {
+  kind: 'action'
+  builder: ActionToolBuilder
+}
+
+export interface ExternalToolSpec extends ToolSpecBase {
+  kind: 'external'
+  builder: ExternalToolBuilder
+}
+
+export type ToolSpec = ReadToolSpec | WriteToolSpec | ActionToolSpec | ExternalToolSpec
+
+// ── 카테고리 (등록 단위) ─────────────────────────────────────────────
+
+/**
+ * 한 도메인 / 패키지가 등록하는 tool 묶음.
+ * 카테고리 이름은 식별자 (debug log / 분쟁 시 origin 추적). unique.
+ */
+export interface ToolCategory {
+  /** 등록 식별자. 예: 'styling', 'board-import', 'fmsim'. */
+  name: string
+  /** 이 카테고리에 속한 tool spec 들. */
+  specs: ToolSpec[]
+  /** 선택 — 디버깅용 짧은 설명. */
+  description?: string
+}