@things-factory/figure-service 10.1.27 → 10.1.29

package/server/service/figure/figure-tool-doors.test.ts

@@ -0,0 +1,143 @@
+/*
+ * figure 도구가 지나는 문 — ADR-0072 결정 2.
+ *
+ * 선언만 해 두고 아무도 읽지 않으면 그 선언은 다음 사람이 지우거나 바꿔도 아무 일이 없다. 여기서는
+ * 실제로 등록된 명세를 등록기에 넣고, 등록기가 무엇도 문제 삼지 않는지 묻는다. 도구 목록이 늘면
+ * 이 시험이 먼저 문다.
+ */
+import { readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+import { clearToolRegistry, getAllToolSpecs, getToolRegistryWarnings } from '@things-factory/ai-client-base'
+
+import { registerFigureToolCategories } from './figure-tools'
+
+describe('figure tools — declared doors', () => {
+  beforeEach(() => {
+    clearToolRegistry()
+    registerFigureToolCategories()
+  })
+  afterAll(() => clearToolRegistry())
+
+  it('★ every figure tool says which doors it reaches, as a list', () => {
+    const undeclared = getAllToolSpecs()
+      .filter(spec => !Array.isArray((spec as any).doors))
+      .map(spec => spec.name)
+
+    expect(undeclared).toEqual([])
+  })
+
+  it('★ a door a tool reaches comes with the privilege that guards it', () => {
+    const unguarded = getAllToolSpecs()
+      .filter(spec => ((spec as any).doors ?? []).length > 0 && !(spec as any).privilege)
+      .map(spec => spec.name)
+
+    expect(unguarded).toEqual([])
+  })
+
+  it('the registry itself finds nothing to report about these specs', () => {
+    expect(getToolRegistryWarnings().map(w => `${w.code}:${w.params.tool ?? ''}`)).toEqual([])
+  })
+})
+
+/*
+ * 베낀 권한이 문의 지시자와 같은가 — ADR-0072 결정 5 (b).
+ *
+ * 권한은 문의 지시자에서 나와야 하는데(ADR-0071 결정 2) 지금은 읽을 자리가 없다: 지시자가 남기는
+ * 것은 (category, privilege) 쌍 목록뿐이고 필드별 지도가 없다. 그래서 도구 명세가 권한을 베껴
+ * 적는다. 베낀 값은 **문이 바뀌어도 안 따라간다** — 문에 권한을 붙이거나 떼거나 이름을 고치면
+ * 도구 명세만 옛 값을 들고 남고, 그때 게이트는 문이 안 묻는 것을 묻거나 문이 묻는 것을 안 묻는다.
+ *
+ * 여기서는 리졸버 원문의 지시자를 읽어 도구가 적은 것과 견준다. AUTH 에 청한 필드별 지도가 서면
+ * 이 시험과 베끼기가 함께 없어진다.
+ */
+describe('figure tools — the copied privilege matches the door', () => {
+  beforeEach(() => {
+    clearToolRegistry()
+    registerFigureToolCategories()
+  })
+  afterAll(() => clearToolRegistry())
+
+  /** 리졸버 원문에서 `Query.figures` 같은 문 이름 → 그 문의 `@privilege` 지시자. */
+  const doorPrivileges = (): Map<string, { category: string; privilege: string; owner: boolean }> => {
+    const found = new Map<string, { category: string; privilege: string; owner: boolean }>()
+
+    for (const file of readdirSync(__dirname).filter(one => one.endsWith('.ts') && !one.endsWith('.test.ts'))) {
+      const lines = readFileSync(join(__dirname, file), 'utf8').split('\n')
+      let privilege: { category: string; privilege: string; owner: boolean } | undefined
+      let kind: 'Query' | 'Mutation' | undefined
+      let decorator = ''
+
+      for (const line of lines) {
+        const declared = /@privilege\(category: "([^"]+)", privilege: "([^"]+)"(, domainOwnerGranted: (true|false))?\)/.exec(line)
+        if (declared) {
+          privilege = { category: declared[1]!, privilege: declared[2]!, owner: declared[4] === 'true' }
+          continue
+        }
+
+        const opens = /@(Query|Mutation)\(/.exec(line)
+        if (opens) {
+          kind = opens[1] as 'Query' | 'Mutation'
+          decorator = line
+          continue
+        }
+
+        if (!kind) {
+          /* 지시자와 문 사이에 딴 것이 오면 그 지시자는 이 문의 것이 아니다. */
+          if (line.trim() && !line.trim().startsWith('@') && !line.trim().startsWith('*') && !line.trim().startsWith('/*')) {
+            privilege = undefined
+          }
+          continue
+        }
+
+        decorator += '\n' + line
+        const method = /^\s*(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(/.exec(line)
+        if (!method) continue
+
+        /*
+          필드 이름이 메서드 이름과 다를 수 있는 길은 하나뿐이다 — 데코레이터의 `name:`. 그것이
+          나타나면 조용히 메서드 이름으로 읽지 않고 멈춘다. 잘못 읽은 짝은 초록으로 보인다.
+        */
+        if (/\bname:\s*'/.test(decorator)) {
+          throw new Error(`${file} 의 ${kind} 가 데코레이터에서 이름을 정한다 — 이 시험이 그 길을 아직 안 읽는다`)
+        }
+
+        if (privilege) found.set(`${kind}.${method[1]}`, privilege)
+        kind = undefined
+        privilege = undefined
+        decorator = ''
+      }
+    }
+
+    return found
+  }
+
+  it('★ 도구가 적은 권한이 그 문의 지시자와 한 글자도 다르지 않다', () => {
+    const doors = doorPrivileges()
+
+    const mismatched = getAllToolSpecs().flatMap(spec =>
+      ((spec as any).doors ?? []).map((door: string) => {
+        const declared = doors.get(door)
+        const copied = (spec as any).privilege
+        if (!declared) return `${spec.name} → ${door}: 그런 문이 없거나 그 문이 권한을 선언하지 않는다`
+        if (
+          declared.category !== copied?.category ||
+          declared.privilege !== copied?.privilege ||
+          declared.owner !== (copied?.owner ?? false)
+        ) {
+          return `${spec.name} → ${door}: 문은 ${JSON.stringify(declared)} 인데 도구는 ${JSON.stringify(copied)}`
+        }
+        return undefined
+      })
+    ).filter(Boolean)
+
+    expect(mismatched).toEqual([])
+  })
+
+  it('견줄 문을 실제로 찾아 읽었다 — 0 건이면 위 시험은 언제나 초록이다', () => {
+    const doors = doorPrivileges()
+    expect(doors.get('Query.figures')).toEqual({ category: 'figure', privilege: 'query', owner: true })
+    expect(doors.get('Mutation.proposeFigure')).toEqual({ category: 'figure', privilege: 'mutation', owner: true })
+    expect(doors.size).toBeGreaterThanOrEqual(4)
+  })
+})

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

@@ -117,7 +117,12 @@ test('실제 registryAssistantChat 경계가 열린 모델 문맥을 Figure 도
     } } as any,
     messages: [{ role: 'user', content: '현재 모델을 조회해줘' }],
     systemPrompt: 'Read the current figure.', toolCategories: ['figure-authoring'],
-    state: { domain: MINE }, hostContext: { figureId: 'fig-1', draftSource: SOURCE }
+    state: { domain: MINE }, hostContext: { figureId: 'fig-1', draftSource: SOURCE },
+    /*
+     * 도구가 닿는 문의 권한을 선언한 뒤로(ADR-0071 결정 2), 권한을 물어볼 길을 주지 않으면 그 도구는
+     * 닫힌다 — 그것이 맞는 기본값이다. 여기서 보는 것은 권한이 아니라 배선이므로 「가진 사람」으로 둔다.
+     */
+    toolAccess: async () => true
   })
   expect(seen).toHaveLength(2)
   expect(JSON.stringify(seen[1])).toContain('MIXER')

package/server/service/figure/figure-tools.ts

@@ -232,7 +232,7 @@ function unsavedFigure(host: any): any | undefined {
 const FIGURE_ID_ARG = {
   figureId: {
     type: 'string',
-    description: 'The figure to read. Omit when host context has an open figureId or an unsaved new editor draft. On the catalog, first resolve the user’s requested figure with listFigures.'
+    description: 'The figure to read. Omit to read the one the person has open, saved or not — the server fills it in, and you cannot see which it is. On the catalog nothing is open, so resolve the figure the person asked for with listFigures first.'
   }
 } as const
 
@@ -247,6 +247,9 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'listFigures',
+      /* 이 도메인의 도형 목록 — 저장소를 직접 읽지만 같은 일을 하는 문은 이것이다. */
+      doors: ['Query.figures'],
+      privilege: { category: 'figure', privilege: 'query', owner: true },
       description:
         'Lists the figures in this tenant with their type names, states and part counts. ' +
         'Call it before naming a type — type names are stored identifiers and must not be invented.',
@@ -274,9 +277,13 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'getFigureSource',
+      /* 저장된 도형의 원본. **저장 전 초안**을 물으면 저장소에 갈 것이 없어 화면이 보낸 것을 그대로 돌려준다 —
+       * 그 갈래에는 닿는 문이 없지만 `doors: []` 로 적지 않는다. 그러면 저장된 도형을 읽는 권한 검사가 선언에서 사라진다. */
+      doors: ['Query.figure'],
+      privilege: { category: 'figure', privilege: 'query', owner: true },
       description:
         'Returns the canonical FigureSource of one figure, with its measured cost ' +
-        '(triangles, draw calls, how many fit on one board). Call it before proposing a revision — ' +
+        '(triangles, part groups, and how many of it hold 60fps on one screen). Call it before proposing a revision — ' +
         'revising without reading it means proposing against a guess.',
       schema: { type: 'object', properties: { ...FIGURE_ID_ARG } },
       builder: async (args: any, ctx: any) => {
@@ -309,6 +316,9 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'inspectFigure',
+      /* 검사 결과 — 같은 일을 하는 문. */
+      doors: ['Query.inspectFigure'],
+      privilege: { category: 'figure', privilege: 'query', owner: true },
       description:
         'Says whether a figure may be released and, when it may not, what is wrong — each finding ' +
         'carries why it is a problem and what to change. Call it when asked about releasing, or ' +
@@ -328,6 +338,9 @@ function figureToolSpecs(): ToolSpec[] {
     {
       kind: 'read',
       name: 'proposeFigureCandidate',
+      /* 후보 생성 — 저장은 하지 않지만 같은 문의 권한을 쓴다. */
+      doors: ['Mutation.proposeFigure'],
+      privilege: { category: 'figure', privilege: 'mutation', owner: true },
       description:
         'Asks for a figure candidate from a description, optionally revising an existing one. ' +
         'Returns the candidate with its score and cost. NOTHING IS SAVED — the author accepts or ' +

package/server/service/figure/figure-type.ts

@@ -41,11 +41,19 @@ export class NewFigure {
 /**
  * 수정.
  *
- * `type` 이 없다. **저장되는 식별자라 고칠 수 없다** — 바꾸면 이미 배치된 보드가
- * 타입을 못 찾아 오류 없이 빈 화면이 된다. 고칠 수 있는 이름은 `name` 뿐이다.
+ * `type` 은 **한 번도 발행되지 않은 초안에서만** 바뀐다(ADR-0063 결정 4). 저장되는 식별자라
+ * 발행된 뒤에 바꾸면 이미 배치된 보드가 타입을 못 찾아 오류 없이 빈 화면이 된다. 발행 전에는
+ * 그 도형을 가리키는 도면이 있을 수 없다 — 도면은 최신 발행판을 그리므로 발행된 적 없는
+ * 도형은 그려질 자리가 없다.
+ *
+ * 닫아 두었더니 저작자가 이름을 한 번도 정하지 못했다. 새 Figure 에는 기계가 지은 이름이
+ * 붙고(`FIGURE_MU6RJH47`) 칸에 자물쇠가 걸려서, 그 이름이 그대로 도면에 적히는 이름이 됐다.
  */
-@InputType({ description: 'Input for updating an existing figure. The `type` field is absent by design — it is a stored identifier.' })
+@InputType({ description: 'Input for updating an existing figure. `type` is accepted only while the figure has never been released.' })
 export class FigurePatch {
+  @Field({ nullable: true, description: 'The stored identifier. Accepted only before the first release; rejected once a version exists.' })
+  type?: string
+
   @Field({ nullable: true, description: 'The new display name.' })
   name?: string