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

package/server/service/import-session/suggest-board-name.test.ts

@@ -0,0 +1,271 @@
+/**
+ * suggestBoardName — 단위 테스트.
+ *
+ * 검증 포인트:
+ *  - base 후보 우선순위 (hint > userPrompt > viewTypeReasoning > attachment stem > fallback)
+ *  - 정규화 (확장자 제거, 특수문자 → 공백, 다중공백 단일화, 50자 절단)
+ *  - 충돌 검사 (도메인 격리, case-insensitive, 가장 작은 (n) 선택)
+ *  - 도메인 안에서 충돌 없으면 base 그대로
+ */
+import {
+  suggestBoardName,
+  suggestBoardMeta,
+  pickAvailableSuffix,
+  type SuggestSessionRepoLike,
+  type SuggestAttachmentRepoLike,
+  type SuggestBoardRepoLike
+} from './suggest-board-name'
+
+function makeDeps(opts: {
+  session?: any
+  attachment?: any
+  existingNames?: string[]
+}) {
+  const sessionRepo: SuggestSessionRepoLike = {
+    findOneBy: async () => opts.session ?? null
+  }
+  const attachmentRepo: SuggestAttachmentRepoLike = {
+    findOneBy: async () => opts.attachment ?? null
+  }
+  const boardRepo: SuggestBoardRepoLike = {
+    findExistingNames: async () => opts.existingNames ?? []
+  }
+  return { sessionRepo, attachmentRepo, boardRepo }
+}
+
+const ctx = { domain: { id: 'domain-1' } }
+
+describe('suggestBoardName — base 후보 우선순위', () => {
+  test('hint 가 있으면 우선 — session 무시', async () => {
+    const deps = makeDeps({
+      session: { id: 's1', optionsJson: JSON.stringify({ userPrompt: 'should be ignored' }) },
+      existingNames: []
+    })
+    const r = await suggestBoardName({ sessionId: 's1', hint: 'My drawing' }, ctx, deps)
+    expect(r).toBe('My drawing')
+  })
+
+  test('hint 없으면 session.options.userPrompt 의 첫 문장', async () => {
+    const deps = makeDeps({
+      session: {
+        id: 's1',
+        optionsJson: JSON.stringify({
+          userPrompt: 'fab lithography zone with stockers. Multiple stockers visible.'
+        })
+      },
+      existingNames: []
+    })
+    const r = await suggestBoardName({ sessionId: 's1' }, ctx, deps)
+    expect(r).toBe('fab lithography zone with stockers')
+  })
+
+  test('userPrompt 없으면 viewTypeReasoning 사용', async () => {
+    const deps = makeDeps({
+      session: {
+        id: 's1',
+        optionsJson: JSON.stringify({}),
+        resultJson: JSON.stringify({
+          boardModel: {
+            importMeta: { viewTypeReasoning: 'isometric 3D rendering with depth' }
+          }
+        })
+      },
+      existingNames: []
+    })
+    const r = await suggestBoardName({ sessionId: 's1' }, ctx, deps)
+    expect(r).toBe('isometric 3D rendering with depth')
+  })
+
+  test('hint/userPrompt/reasoning 모두 없으면 attachment.name stem', async () => {
+    const deps = makeDeps({
+      session: { id: 's1', attachmentId: 'a1', optionsJson: '{}', resultJson: null },
+      attachment: { id: 'a1', name: 'factory_plan_v3.png' },
+      existingNames: []
+    })
+    const r = await suggestBoardName({ sessionId: 's1' }, ctx, deps)
+    expect(r).toBe('factory plan v3') // _-. → 공백
+  })
+
+  test('어떤 후보도 없으면 fallback "Imported board"', async () => {
+    const deps = makeDeps({})
+    const r = await suggestBoardName({}, ctx, deps)
+    expect(r).toBe('Imported board')
+  })
+
+  test('session 자체가 미존재면 fallback', async () => {
+    const deps = makeDeps({ session: null })
+    const r = await suggestBoardName({ sessionId: 'x' }, ctx, deps)
+    expect(r).toBe('Imported board')
+  })
+})
+
+describe('suggestBoardName — 정규화', () => {
+  test('확장자 제거', async () => {
+    const deps = makeDeps({
+      session: { id: 's1', attachmentId: 'a1', optionsJson: '{}' },
+      attachment: { id: 'a1', name: 'plant.dxf' },
+      existingNames: []
+    })
+    const r = await suggestBoardName({ sessionId: 's1' }, ctx, deps)
+    expect(r).toBe('plant')
+  })
+
+  test('_-. 다중 → 단일 공백', async () => {
+    const r = await suggestBoardName({ hint: 'foo___bar---baz' }, ctx, makeDeps({}))
+    expect(r).toBe('foo bar baz')
+  })
+
+  test('50자 초과 절단 + trim', async () => {
+    const longHint = 'a'.repeat(80) + ' final'
+    const r = await suggestBoardName({ hint: longHint }, ctx, makeDeps({}))
+    expect(r.length).toBeLessThanOrEqual(50)
+  })
+})
+
+describe('suggestBoardName — 충돌 회피', () => {
+  test('충돌 없으면 base 그대로', async () => {
+    const deps = makeDeps({ existingNames: [] })
+    const r = await suggestBoardName({ hint: 'My drawing' }, ctx, deps)
+    expect(r).toBe('My drawing')
+  })
+
+  test('정확 충돌 시 (2) 부여', async () => {
+    const deps = makeDeps({ existingNames: ['My drawing'] })
+    const r = await suggestBoardName({ hint: 'My drawing' }, ctx, deps)
+    expect(r).toBe('My drawing (2)')
+  })
+
+  test('(2) 까지 있으면 (3)', async () => {
+    const deps = makeDeps({
+      existingNames: ['My drawing', 'My drawing (2)']
+    })
+    const r = await suggestBoardName({ hint: 'My drawing' }, ctx, deps)
+    expect(r).toBe('My drawing (3)')
+  })
+
+  test('case-insensitive 비교 — "MY DRAWING" 도 충돌로 간주', async () => {
+    const deps = makeDeps({ existingNames: ['MY DRAWING'] })
+    const r = await suggestBoardName({ hint: 'My drawing' }, ctx, deps)
+    expect(r).toBe('My drawing (2)')
+  })
+
+  test('중간 빈 슬롯 — (3) 만 있으면 base 가 비어있으니 base 그대로', async () => {
+    // 'Foo' 가 비어있으면 그것 반환. (3) 만 있어도 base 가 비어있으니 base 우선.
+    const deps = makeDeps({ existingNames: ['Foo (3)'] })
+    const r = await suggestBoardName({ hint: 'Foo' }, ctx, deps)
+    expect(r).toBe('Foo')
+  })
+})
+
+describe('pickAvailableSuffix 단위', () => {
+  test('빈 existingNames → base', () => {
+    expect(pickAvailableSuffix('foo', [])).toBe('foo')
+  })
+  test('base 만 충돌 → (2)', () => {
+    expect(pickAvailableSuffix('foo', ['foo'])).toBe('foo (2)')
+  })
+  test('base, (2), (3) 다 충돌 → (4)', () => {
+    expect(pickAvailableSuffix('foo', ['foo', 'foo (2)', 'foo (3)'])).toBe('foo (4)')
+  })
+  test('(2) 만 차있고 base 비어있으면 base 반환', () => {
+    expect(pickAvailableSuffix('foo', ['foo (2)'])).toBe('foo')
+  })
+})
+
+// ── suggestBoardMeta — 짧은 이름 + 자세한 description ──────────────────
+
+describe('suggestBoardMeta — 보드 정체성 (subject) 기반', () => {
+  test('VLM subjectName + subjectDescription 이 우선 — 보드 정체성', async () => {
+    const deps = makeDeps({
+      session: {
+        id: 's1',
+        optionsJson: JSON.stringify({ userPrompt: '강조하고 싶은 부분' }),
+        resultJson: JSON.stringify({
+          metadata: {
+            subjectName: 'Lithography zone',
+            subjectDescription:
+              'fab lithography 구역 — 6개 stocker 가 좌측 벽을 따라 배치, 중앙에 컨베이어 라인.',
+            // 다음은 transient 메타 — description 에 들어가면 안 됨
+            importStrategy: 'AI 가 stocker 6개와 conveyor 라인을 식별했습니다.',
+            userPrompt: '강조하고 싶은 부분'
+          },
+          categoryDistribution: { container: 6, path: 3 }
+        })
+      },
+      existingNames: []
+    })
+    const r = await suggestBoardMeta({ sessionId: 's1' }, ctx, deps)
+    expect(r.name).toBe('Lithography zone')
+    expect(r.description).toContain('fab lithography 구역')
+    // transient 메타가 description 에 안 들어가야 함
+    expect(r.description).not.toContain('AI 가 stocker')
+    expect(r.description).not.toContain('총 ')
+    expect(r.description).not.toContain('container: 6')
+  })
+
+  test('명시 input.hint 가 있으면 name 우선 — 사용자 의도가 가장 직접적', async () => {
+    const deps = makeDeps({
+      session: {
+        id: 's1',
+        resultJson: JSON.stringify({
+          metadata: { subjectName: 'AI subject' }
+        })
+      },
+      existingNames: []
+    })
+    const r = await suggestBoardMeta({ sessionId: 's1', hint: 'My drawing' }, ctx, deps)
+    expect(r.name).toBe('My drawing')
+  })
+
+  test('subject 가 없으면 attachment.name stem fallback', async () => {
+    const deps = makeDeps({
+      session: { id: 's1', attachmentId: 'a1', optionsJson: '{}', resultJson: '{}' },
+      attachment: { id: 'a1', name: 'plant.dxf' },
+      existingNames: []
+    })
+    const r = await suggestBoardMeta({ sessionId: 's1' }, ctx, deps)
+    expect(r.name).toBe('plant')
+  })
+
+  test('description 우선순위 — subjectDescription > input.hint > 빈 문자열', async () => {
+    const deps = makeDeps({})
+    const r1 = await suggestBoardMeta({ hint: 'hint description' }, ctx, deps)
+    expect(r1.description).toBe('hint description')
+
+    const deps2 = makeDeps({})
+    const r2 = await suggestBoardMeta({}, ctx, deps2)
+    expect(r2.description).toBe('')
+  })
+
+  test('subjectName 이 30자 초과면 잘림', async () => {
+    const longSubject = 'A very long subject name that exceeds thirty characters limit'
+    const deps = makeDeps({
+      session: {
+        id: 's1',
+        resultJson: JSON.stringify({ metadata: { subjectName: longSubject } })
+      },
+      existingNames: []
+    })
+    const r = await suggestBoardMeta({ sessionId: 's1' }, ctx, deps)
+    expect(r.name.length).toBeLessThanOrEqual(30)
+  })
+
+  test('아무 정보 없으면 fallback name + 빈 description', async () => {
+    const deps = makeDeps({})
+    const r = await suggestBoardMeta({}, ctx, deps)
+    expect(r.name).toBe('Imported board')
+    expect(r.description).toBe('')
+  })
+
+  test('이름 충돌 검사는 동일 — (2) suffix 부여', async () => {
+    const deps = makeDeps({
+      session: {
+        id: 's1',
+        resultJson: JSON.stringify({ metadata: { subjectName: 'Lithography zone' } })
+      },
+      existingNames: ['Lithography zone']
+    })
+    const r = await suggestBoardMeta({ sessionId: 's1' }, ctx, deps)
+    expect(r.name).toBe('Lithography zone (2)')
+  })
+})

package/server/service/import-session/suggest-board-name.ts

@@ -0,0 +1,279 @@
+/**
+ * suggestBoardName — ImportSession 으로부터 새 Board 의 후보 이름을 추천한다.
+ *
+ * 정책:
+ *   1) base 후보 우선순위: input.hint → session.options.userPrompt → session.result.metadata.viewTypeReasoning
+ *      → attachment.name stem → 'Imported board'
+ *   2) base 정규화: 확장자 제거, _-. → 공백, 다중 공백 단일화, 50자 절단, trim
+ *   3) 도메인 격리 + 단일 LIKE query: `WHERE domain_id = ? AND (name = base OR name LIKE 'base (%)')`
+ *      한 번에 충돌 후보 다 가져오고 메모리에서 사용 가능한 가장 작은 (n) 결정
+ *   4) 결과: base 가 충돌 없으면 base, 있으면 'base (2)' / 'base (3)' / ...
+ *
+ * materializeFromSession 과 동일한 *RepoLike 패턴 — typeorm 의존성 주입으로 단위테스트 가능.
+ */
+
+const FALLBACK = 'Imported board'
+
+export interface SuggestBoardNameInput {
+  /** ImportSession id — 옵션. 있으면 거기서 hint / attachment 정보 추출. */
+  sessionId?: string
+  /**
+   * 명시 hint. session 정보보다 우선. 사용자가 wizard 에서 직접 메모를 쳐서 그것 기반 추천을
+   * 받고 싶을 때 사용.
+   */
+  hint?: string
+}
+
+export interface SessionForSuggest {
+  id: string
+  attachmentId?: string
+  optionsJson?: string | null
+  resultJson?: string | null
+}
+
+export interface AttachmentForSuggest {
+  id: string
+  name?: string
+}
+
+export interface SuggestSessionRepoLike {
+  findOneBy(criteria: any): Promise<SessionForSuggest | null>
+}
+
+export interface SuggestAttachmentRepoLike {
+  findOneBy(criteria: any): Promise<AttachmentForSuggest | null>
+}
+
+export interface SuggestBoardRepoLike {
+  /**
+   * 도메인 격리된 LIKE 쿼리. find({ where: { name: Like('base%'), domain: { id } } }) 형태로
+   * 호출자가 wiring. typeorm Like operator 노출을 피하기 위해 단순 string 으로 받음.
+   */
+  findExistingNames(opts: { domainId: string; basePrefix: string }): Promise<string[]>
+}
+
+export interface SuggestContext {
+  domain: { id: string; [k: string]: any }
+}
+
+export interface SuggestDeps {
+  sessionRepo: SuggestSessionRepoLike
+  attachmentRepo: SuggestAttachmentRepoLike
+  boardRepo: SuggestBoardRepoLike
+}
+
+export async function suggestBoardName(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<string> {
+  const base = await resolveBaseName(input, context, deps)
+  const cleaned = sanitize(base) || FALLBACK
+
+  const existingNames = await deps.boardRepo.findExistingNames({
+    domainId: context.domain.id,
+    basePrefix: cleaned
+  })
+  return pickAvailableSuffix(cleaned, existingNames)
+}
+
+/**
+ * Board 이름 + 설명을 함께 추천. 이름은 짧고 심플 (운영 카드/리스트 표시용),
+ * 설명은 자세히 (사용자 hint + AI importStrategy + 통계 요약).
+ *
+ * 정책:
+ *   - **name**: hint / userPrompt / VLM reasoning / attachment stem 에서 짧은 base 추출 후
+ *     30자 이내로 자르고, 충돌 검사 + (n) suffix
+ *   - **description**: userPrompt + AI importStrategy + (있으면) reasoning + 카테고리 분포
+ *     를 자연어 단락으로 합성. 없으면 빈 문자열
+ */
+export interface SuggestBoardMetaResult {
+  name: string
+  description: string
+}
+
+export async function suggestBoardMeta(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<SuggestBoardMetaResult> {
+  // 보드 정체성 = AI 가 도면을 보고 식별한 subject. import 처리 메타 (importStrategy /
+  // categoryDist / userPrompt — AI 에게 한 지시) 와는 별 차원이라 영속 데이터에 섞지 않는다.
+  const { subjectName, subjectDescription } = await resolveSubject(input, context, deps)
+
+  // name: subjectName > input.hint > attachment.name stem > FALLBACK
+  // 사용자가 명시 hint 를 줬으면 그것이 우선 (직접 의도). VLM subjectName 은 그 다음.
+  const baseName =
+    (input.hint && input.hint.trim() && firstSentence(input.hint)) ||
+    subjectName ||
+    (await resolveAttachmentStem(input, context, deps)) ||
+    FALLBACK
+  const cleanedName = shortenName(sanitize(baseName) || FALLBACK)
+
+  const existingNames = await deps.boardRepo.findExistingNames({
+    domainId: context.domain.id,
+    basePrefix: cleanedName
+  })
+  const name = pickAvailableSuffix(cleanedName, existingNames)
+
+  // description: subjectDescription > input.hint (full) > 빈 문자열
+  // AI 가 도면을 본 자세한 묘사가 있으면 그것이 가장 가치 있음.
+  const description =
+    subjectDescription || (input.hint && input.hint.trim()) || ''
+
+  return { name, description }
+}
+
+/** AI 가 도면을 보고 식별한 subject (보드 정체성) — VLM 응답의 subjectName / subjectDescription. */
+async function resolveSubject(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<{ subjectName?: string; subjectDescription?: string }> {
+  if (!input.sessionId) return {}
+  const session = await deps.sessionRepo.findOneBy({
+    id: input.sessionId,
+    domain: { id: context.domain.id }
+  })
+  if (!session) return {}
+  const result = parseJsonSafe(session.resultJson)
+  const subjectName = typeof result?.metadata?.subjectName === 'string'
+    ? result.metadata.subjectName.trim()
+    : undefined
+  const subjectDescription = typeof result?.metadata?.subjectDescription === 'string'
+    ? result.metadata.subjectDescription.trim()
+    : undefined
+  return { subjectName, subjectDescription }
+}
+
+/** subject 미산출 시 fallback — attachment.name stem 만. */
+async function resolveAttachmentStem(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<string | undefined> {
+  if (!input.sessionId) return undefined
+  const session = await deps.sessionRepo.findOneBy({
+    id: input.sessionId,
+    domain: { id: context.domain.id }
+  })
+  if (!session?.attachmentId) return undefined
+  const att = await deps.attachmentRepo.findOneBy({
+    id: session.attachmentId,
+    domain: { id: context.domain.id }
+  })
+  return stemOf(att?.name) || undefined
+}
+
+/**
+ * 짧은 이름 — 단순 30자 단위로 단어 경계에서 자르기. 너무 길면 그대로 자르되 단어 보존.
+ */
+function shortenName(s: string): string {
+  if (s.length <= 30) return s
+  // 30자 이내 마지막 공백에서 자르기
+  const truncated = s.slice(0, 30)
+  const lastSpace = truncated.lastIndexOf(' ')
+  if (lastSpace > 10) return truncated.slice(0, lastSpace).trim()
+  return truncated.trim()
+}
+
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+async function resolveBaseName(
+  input: SuggestBoardNameInput,
+  context: SuggestContext,
+  deps: SuggestDeps
+): Promise<string> {
+  // 1) 명시 hint
+  if (input.hint && input.hint.trim()) return firstSentence(input.hint)
+
+  // 2) session 정보
+  if (input.sessionId) {
+    const session = await deps.sessionRepo.findOneBy({
+      id: input.sessionId,
+      domain: { id: context.domain.id }
+    })
+    if (session) {
+      // 2a) userPrompt 우선
+      const opts = parseJsonSafe(session.optionsJson)
+      const userPrompt = typeof opts?.userPrompt === 'string' ? opts.userPrompt.trim() : ''
+      if (userPrompt) return firstSentence(userPrompt)
+
+      // 2b) VLM reasoning
+      const result = parseJsonSafe(session.resultJson)
+      const reasoning =
+        typeof result?.boardModel?.importMeta?.viewTypeReasoning === 'string'
+          ? result.boardModel.importMeta.viewTypeReasoning.trim()
+          : typeof result?.metadata?.viewTypeReasoning === 'string'
+          ? result.metadata.viewTypeReasoning.trim()
+          : ''
+      if (reasoning) return firstSentence(reasoning)
+
+      // 2c) attachment name stem
+      if (session.attachmentId) {
+        const att = await deps.attachmentRepo.findOneBy({
+          id: session.attachmentId,
+          domain: { id: context.domain.id }
+        })
+        const stem = stemOf(att?.name)
+        if (stem) return stem
+      }
+    }
+  }
+
+  return FALLBACK
+}
+
+function parseJsonSafe(s: string | null | undefined): any {
+  if (!s) return undefined
+  try {
+    return JSON.parse(s)
+  } catch {
+    return undefined
+  }
+}
+
+function firstSentence(text: string): string {
+  // 첫 문장 종결 부호 또는 줄바꿈까지. 미발견 시 전체.
+  const m = text.match(/^([^.\n!?]{1,120})[.\n!?]?/)
+  return (m?.[1] ?? text).trim()
+}
+
+function stemOf(name: string | undefined | null): string {
+  if (!name) return ''
+  // 마지막 . 이후 (확장자) 제거. 점이 여러 번이면 가장 마지막만.
+  const lastDot = name.lastIndexOf('.')
+  if (lastDot > 0) return name.slice(0, lastDot)
+  return name
+}
+
+/**
+ * 정규화: _-. → 공백, 다중 공백 단일화, trim, 50자 절단.
+ * 결과가 빈 문자열이면 '' 반환 (호출자가 fallback).
+ */
+function sanitize(s: string): string {
+  if (!s) return ''
+  let cleaned = s.replace(/[_\-.]+/g, ' ').replace(/\s+/g, ' ').trim()
+  if (cleaned.length > 50) cleaned = cleaned.slice(0, 50).trim()
+  return cleaned
+}
+
+/**
+ * existingNames 안에서 base 가 그대로 비어있으면 base 반환, 아니면 'base (2)', '(3)', ...
+ * case-insensitive 비교 (postgres ilike 호환).
+ */
+export function pickAvailableSuffix(base: string, existingNames: string[]): string {
+  const lower = base.toLowerCase()
+  const taken = new Set<string>()
+  for (const name of existingNames) {
+    if (typeof name === 'string') taken.add(name.toLowerCase())
+  }
+  if (!taken.has(lower)) return base
+  for (let n = 2; n < 10000; n++) {
+    const candidate = `${base} (${n})`
+    if (!taken.has(candidate.toLowerCase())) return candidate
+  }
+  // 9999개 충돌 이라는 비현실 시나리오 — 마지막 fallback
+  return `${base} (${Date.now()})`
+}

package/server/service/import-tools.test.ts

@@ -0,0 +1,137 @@
+/**
+ * board-import 의 LLM tool 등록 + builder wiring — 단위 테스트.
+ *
+ * registry 통합 (등록 / kind 분류 / schema 노출) 외에 builder 가 service 함수와 정확히
+ * 결합되었는지 검증. service 함수 본체는 별도 파일 (import-actions.test, materialize-from-
+ * session.test) 에서 검증되어 있으므로 본 파일은 wiring 만 — ctx 누락 / placeholder 미사용
+ * 회귀 방지.
+ */
+import {
+  clearToolRegistry,
+  findToolSpec,
+  getToolKind,
+  getCategorySpecs
+} from '@things-factory/ai-client-base'
+import { registerBoardImportTools } from './import-tools'
+
+beforeEach(() => {
+  clearToolRegistry()
+  registerBoardImportTools()
+})
+
+afterEach(() => {
+  clearToolRegistry()
+})
+
+// ── 카테고리 등록 검증 ─────────────────────────────────────────────
+
+describe('import-tools — 카테고리 등록', () => {
+  test("'board-import' 카테고리 등록", () => {
+    expect(getCategorySpecs('board-import').length).toBeGreaterThan(0)
+  })
+
+  test('listImportAdapters / importBoardAsync / getImportSession / materializeImportSession 모두 등록', () => {
+    expect(findToolSpec('listImportAdapters')).toBeDefined()
+    expect(findToolSpec('importBoardAsync')).toBeDefined()
+    expect(findToolSpec('getImportSession')).toBeDefined()
+    expect(findToolSpec('materializeImportSession')).toBeDefined()
+  })
+})
+
+// ── kind 분류 ────────────────────────────────────────────────────
+
+describe('import-tools — kind 분류', () => {
+  test('listImportAdapters / getImportSession 은 read', () => {
+    expect(getToolKind('listImportAdapters')).toBe('read')
+    expect(getToolKind('getImportSession')).toBe('read')
+  })
+
+  test('importBoardAsync / materializeImportSession 은 external', () => {
+    expect(getToolKind('importBoardAsync')).toBe('external')
+    expect(getToolKind('materializeImportSession')).toBe('external')
+  })
+})
+
+// ── schema 노출 ──────────────────────────────────────────────────
+
+describe('import-tools — schema 노출', () => {
+  test('importBoardAsync schema 가 attachmentId required', () => {
+    const spec = findToolSpec('importBoardAsync')
+    expect(spec?.schema?.required).toContain('attachmentId')
+  })
+
+  test('materializeImportSession schema 가 sessionId / name required + type enum', () => {
+    const spec = findToolSpec('materializeImportSession')
+    expect(spec?.schema?.required).toEqual(expect.arrayContaining(['sessionId', 'name']))
+    expect(spec?.schema?.properties?.type?.enum).toEqual(['main', 'sub', 'popup'])
+  })
+
+  test('materializeImportSession 은 사용자 confirm 강조 themeNote 보유', () => {
+    const spec = findToolSpec('materializeImportSession')
+    expect(spec?.themeNote).toContain('confirm')
+  })
+})
+
+// ── builder wiring — ctx 누락 시 명확 에러 ───────────────────────────
+
+describe('import-tools — builder ctx 누락', () => {
+  test('importBoardAsync 가 ctx.state 없으면 의미있는 에러', async () => {
+    const spec = findToolSpec('importBoardAsync')
+    if (spec?.kind !== 'external') throw new Error('expected external')
+    await expect(spec.builder({ attachmentId: 'a1' }, {})).rejects.toThrow(/ctx\.state\.domain/)
+  })
+
+  test('getImportSession 가 ctx.state 없으면 의미있는 에러', async () => {
+    const spec = findToolSpec('getImportSession')
+    if (spec?.kind !== 'read') throw new Error('expected read')
+    await expect(spec.builder({ sessionId: 's1' }, {})).rejects.toThrow(/ctx\.state\.domain/)
+  })
+
+  test('materializeImportSession 가 ctx.state 없으면 의미있는 에러', async () => {
+    const spec = findToolSpec('materializeImportSession')
+    if (spec?.kind !== 'external') throw new Error('expected external')
+    await expect(
+      spec.builder({ sessionId: 's1', name: 'New' }, {})
+    ).rejects.toThrow(/ctx\.state\.domain/)
+  })
+})
+
+// ── builder wiring — listImportAdapters (ctx 무관) ───────────────────
+//
+// listImportAdapters builder 는 require('./pipeline/index') 로 DEFAULT_ADAPTERS 를
+// inspect 한다. pipeline 모듈 load chain (DxfAdapter / ImageAdapter / ai-client-base /
+// 외부 라이브러리) 의 typeorm-bound 또는 type-graphql Field reflection 평가가 단위 test
+// 환경에서 fail 하므로 본 단위 테스트에서는 격리 어렵다 — 통합 test (실 server bootstrap
+// 환경) 또는 e2e 에서 검증해야 한다. 핵심 wiring (kind / schema / ctx 누락 에러) 은
+// 위 describe 블록들이 충분히 보호.
+//
+// 향후 jest setup 에서 type-graphql / typeorm DataSource init 을 mock 해 격리 가능하면
+// describe.skip → describe 로 복원.
+describe.skip('import-tools — listImportAdapters (통합 test 영역)', () => {
+  test('AdapterInfo 배열 반환 — DXF 와 image 적어도 노출', async () => {
+    const spec = findToolSpec('listImportAdapters')
+    if (spec?.kind !== 'read') throw new Error('expected read')
+    const r = await spec.builder({}, {})
+    expect(Array.isArray(r)).toBe(true)
+    const formats = (r as any[]).map(a => a.format)
+    expect(formats).toContain('dxf')
+    expect(formats).toContain('image')
+  })
+
+  test('AdapterInfo 의 capabilities 가 모든 boolean 5 필드 보유', async () => {
+    const spec = findToolSpec('listImportAdapters')
+    if (spec?.kind !== 'read') throw new Error('expected read')
+    const r = await spec.builder({}, {})
+    for (const info of r as any[]) {
+      expect(info.capabilities).toEqual(
+        expect.objectContaining({
+          has2D: expect.any(Boolean),
+          has3D: expect.any(Boolean),
+          hasSemanticLabels: expect.any(Boolean),
+          hasTextLabels: expect.any(Boolean),
+          hasAttributes: expect.any(Boolean)
+        })
+      )
+    }
+  })
+})