@things-factory/figure-service 10.1.117 → 10.1.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.117",
+  "version": "10.1.122",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,16 +25,18 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.3.3",
+    "@hatiolab/figure-model": "^0.4.0",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.114",
-    "@things-factory/attachment-base": "^10.1.116",
-    "@things-factory/auth-base": "^10.1.116",
+    "@things-factory/attachment-base": "^10.1.122",
+    "@things-factory/auth-base": "^10.1.122",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.106",
+    "@things-factory/setting-base": "^10.1.122",
+    "@things-factory/shell": "^10.1.122",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
+    "jszip": "^3.10.1",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "cab2426c1c6e63b53a0a2087eef28c9c55df71dd"
+  "gitHead": "a66715e94ef6064cade05229de57d0fe5798d1fb"
 }

package/scripts/rename-figures-to-full-names.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/*
+ * One-off: moves a development database to full figure names (ADR-0114, design figure-library.md §11 · P4).
+ *
+ *   type  ROBOT_ARM  →  robot-arm          figures · figure_histories · figures.superseded_by
+ *   namespace        →  the given one       figures · figure_histories (column added when missing)
+ *   setting          figure-namespace = the given one, for the domain that holds the figures
+ *   board nodes      ROBOT_ARM  →  {namespace}/robot-arm   boards.model · board_histories.model
+ *
+ * Dry run by default: it prints the plan, the checks and the counts and changes nothing. `--apply` runs it in one
+ * transaction and refuses, changing nothing, when a check fails. Not a migration file -- it is run once by hand.
+ *
+ *   node scripts/rename-figures-to-full-names.mjs --db <path/to/db.sqlite> --namespace system [--apply]
+ */
+import { createRequire } from 'node:module'
+import { randomUUID } from 'node:crypto'
+
+const require = createRequire(import.meta.url)
+const Database = require('better-sqlite3')
+const { isFigureNamespace, isFigureType } = await import(require.resolve('@hatiolab/figure-model'))
+
+const args = process.argv.slice(2)
+const option = name => {
+  const i = args.indexOf(`--${name}`)
+  return i >= 0 ? args[i + 1] : undefined
+}
+const dbPath = option('db')
+const namespace = option('namespace')
+const apply = args.includes('--apply')
+
+if (!dbPath || !namespace) {
+  console.error('usage: --db <path> --namespace <namespace> [--apply]')
+  process.exit(2)
+}
+if (!isFigureNamespace(namespace)) {
+  console.error(`'${namespace}' is not a namespace (lower-case domain-name form, 63 characters at most)`)
+  process.exit(2)
+}
+
+const db = new Database(dbPath, { readonly: !apply, fileMustExist: true })
+const hasTable = name => !!db.prepare(`select 1 from sqlite_master where type='table' and name=?`).get(name)
+const hasColumn = (table, column) => !!db.prepare(`select 1 from pragma_table_info(?) where name=?`).get(table, column)
+
+/** An old type in the shape boards used: capitals, digits and underscores. */
+const OLD_TYPE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$/
+const kebab = type => type.toLowerCase().replace(/_+/g, '-')
+
+/* ── what is there ─────────────────────────────────────────────────────────────────────────────────────────── */
+
+function counts() {
+  const one = sql => db.prepare(sql).pluck().get()
+  const ns = (table) => (hasColumn(table, 'namespace') ? one(`select count(*) from ${table} where namespace is null`) : one(`select count(*) from ${table}`))
+  return {
+    figures: one('select count(*) from figures'),
+    figuresLive: one('select count(*) from figures where deleted_at is null'),
+    histories: one('select count(*) from figure_histories'),
+    figuresOldType: db.prepare('select type from figures').pluck().all().filter(t => OLD_TYPE.test(t)).length,
+    historiesOldType: db.prepare('select type from figure_histories').pluck().all().filter(t => t && OLD_TYPE.test(t)).length,
+    figuresWithoutNamespace: ns('figures'),
+    historiesWithoutNamespace: ns('figure_histories'),
+    namespaceSettings: one(`select count(*) from settings where name='figure-namespace'`),
+    boardNodesOldType: boardNodes().old,
+    boardNodesFullName: boardNodes().full
+  }
+}
+
+/** Board model nodes naming a figure type of this database, in the old shape or already full. */
+function boardNodes(map = typeMap) {
+  let old = 0
+  let full = 0
+  for (const table of ['boards', 'board_histories']) {
+    if (!hasTable(table)) continue
+    for (const { model } of db.prepare(`select model from ${table}`).all()) {
+      walkTypes(model, type => {
+        if (map.has(type)) old++
+        else if (type.includes('/') && [...map.values()].some(t => type === `${namespace}/${t}`)) full++
+      })
+    }
+  }
+  return { old, full }
+}
+
+function walkTypes(text, visit) {
+  let model
+  try {
+    model = JSON.parse(text || '{}')
+  } catch {
+    return
+  }
+  const walk = node => {
+    for (const child of Array.isArray(node?.components) ? node.components : []) {
+      if (typeof child?.type === 'string') visit(child.type, child)
+      walk(child)
+    }
+  }
+  walk(model)
+}
+
+/* ── the plan and its checks ───────────────────────────────────────────────────────────────────────────────── */
+
+const domains = db.prepare('select distinct domain_id as id from figures').pluck().all()
+const problems = []
+if (domains.length !== 1) problems.push(`figures are in ${domains.length} domains; this script moves one domain`)
+const domainId = domains[0]
+
+const rows = db.prepare('select id, type, deleted_at as deletedAt from figures where domain_id = ?').all(domainId)
+const historyTypes = db.prepare('select distinct type from figure_histories where domain_id = ? and type is not null').pluck().all(domainId)
+const typeMap = new Map()
+for (const type of new Set([...rows.map(r => r.type), ...historyTypes])) {
+  if (!OLD_TYPE.test(type)) continue
+  typeMap.set(type, kebab(type))
+}
+
+/* Every new name must be a type, and two old names must never land on one new name among the live figures. */
+for (const [from, to] of typeMap) if (!isFigureType(to)) problems.push(`${from} → ${to} is not a figure type`)
+const liveByNew = new Map()
+for (const row of rows.filter(r => !r.deletedAt)) {
+  const to = typeMap.get(row.type) ?? row.type
+  if (liveByNew.has(to)) problems.push(`${liveByNew.get(to)} and ${row.type} would both become ${to}`)
+  else liveByNew.set(to, row.type)
+}
+const deletedClashes = rows.filter(r => r.deletedAt && liveByNew.has(typeMap.get(r.type) ?? r.type) && liveByNew.get(typeMap.get(r.type) ?? r.type) !== r.type)
+
+const setting = db.prepare(`select value from settings where name='figure-namespace' and domain_id = ?`).get(domainId)
+if (setting && setting.value !== namespace) problems.push(`the domain setting figure-namespace is already ${setting.value}`)
+if (hasColumn('figures', 'namespace')) {
+  const others = db.prepare('select distinct namespace from figures where domain_id = ? and namespace is not null and namespace != ?').pluck().all(domainId, namespace)
+  if (others.length) problems.push(`figures already carry another namespace: ${others.join(', ')}`)
+}
+
+const before = counts()
+console.log(`database   ${dbPath}`)
+console.log(`domain     ${db.prepare('select name from domains where id = ?').pluck().get(domainId) ?? domainId}`)
+console.log(`namespace  ${namespace}`)
+console.log(`renames    ${typeMap.size}`)
+for (const [from, to] of [...typeMap].sort()) console.log(`  ${from.padEnd(28)} → ${to}`)
+if (deletedClashes.length) console.log(`note: deleted figures sharing a new name with a live one (kept, outside the unique index): ${deletedClashes.map(r => r.type).join(', ')}`)
+console.log('before', before)
+
+if (problems.length) {
+  console.error('\nrefused, nothing changed:')
+  for (const problem of problems) console.error(`  - ${problem}`)
+  process.exit(1)
+}
+if (!apply) {
+  console.log('\ndry run: nothing changed. run again with --apply.')
+  process.exit(0)
+}
+
+/* ── apply, in one transaction ─────────────────────────────────────────────────────────────────────────────── */
+
+db.transaction(() => {
+  for (const table of ['figures', 'figure_histories']) {
+    if (!hasColumn(table, 'namespace')) db.exec(`alter table ${table} add column namespace varchar`)
+  }
+
+  const now = new Date().toISOString().replace('T', ' ').slice(0, 19)
+  if (!setting) {
+    db.prepare(`insert into settings (id, name, description, category, value, created_at, updated_at, domain_id) values (?, 'figure-namespace', 'namespace of the figures made here (ADR-0114)', 'figure', ?, ?, ?, ?)`)
+      .run(randomUUID(), namespace, now, now, domainId)
+  }
+
+  const renameFigure = db.prepare('update figures set type = ? where domain_id = ? and type = ?')
+  const renameHistory = db.prepare('update figure_histories set type = ? where domain_id = ? and type = ?')
+  const renameSuperseded = db.prepare('update figures set superseded_by = ? where domain_id = ? and superseded_by = ?')
+  for (const [from, to] of typeMap) {
+    renameFigure.run(to, domainId, from)
+    renameHistory.run(to, domainId, from)
+    renameSuperseded.run(to, domainId, from)
+  }
+  db.prepare('update figures set namespace = ? where domain_id = ? and namespace is null').run(namespace, domainId)
+  db.prepare('update figure_histories set namespace = ? where domain_id = ? and namespace is null').run(namespace, domainId)
+
+  for (const table of ['boards', 'board_histories']) {
+    if (!hasTable(table)) continue
+    const update = db.prepare(`update ${table} set model = ? where id = ?`)
+    for (const { id, model } of db.prepare(`select id, model from ${table} where domain_id = ?`).all(domainId)) {
+      let changed = false
+      let parsed
+      try {
+        parsed = JSON.parse(model || '{}')
+      } catch {
+        continue
+      }
+      const walk = node => {
+        for (const child of Array.isArray(node?.components) ? node.components : []) {
+          if (typeof child?.type === 'string' && typeMap.has(child.type)) {
+            child.type = `${namespace}/${typeMap.get(child.type)}`
+            changed = true
+          }
+          walk(child)
+        }
+      }
+      walk(parsed)
+      if (changed) update.run(JSON.stringify(parsed), id)
+    }
+  }
+
+  const after = counts()
+  const wrong = []
+  if (after.figures !== before.figures) wrong.push('figure count changed')
+  if (after.histories !== before.histories) wrong.push('history count changed')
+  if (after.figuresOldType || after.historiesOldType) wrong.push('old type names remain')
+  if (after.figuresWithoutNamespace || after.historiesWithoutNamespace) wrong.push('rows without a namespace remain')
+  if (after.namespaceSettings < 1) wrong.push('the namespace setting is missing')
+  if (after.boardNodesOldType) wrong.push('board nodes with old names remain')
+  console.log('after ', after)
+  if (wrong.length) throw new Error(`checks after the change failed, rolled back: ${wrong.join(', ')}`)
+})()
+
+console.log('\napplied.')

package/server/routers/figure-package-router.ts

@@ -0,0 +1,53 @@
+import Router from 'koa-router'
+
+import { checkPermission } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+import { Refusal, speakRefusal } from '@things-factory/shell'
+
+import { figurePackageOf } from '../service/figure/figure-package-export.js'
+
+/**
+ * Released figures as a package file to download (ADR-0114 결정 3): `GET /figure-package?refs=ns/type@v,...`.
+ *
+ * The same door as `figureBlueprint` (`figure-published`, domain owners included). The manifest names where the
+ * releases can be had again: `figure.publicUrl` in the server config, or this request's origin.
+ */
+export const figurePackageRouter = new Router()
+
+figurePackageRouter.get('/figure-package', async context => {
+  const { domain, user, unsafeIP, prohibitedPrivileges } = context.state
+  const allowed = await checkPermission(
+    { category: 'figure-published', privilege: 'query', owner: true },
+    user,
+    domain,
+    unsafeIP,
+    prohibitedPrivileges
+  )
+  if (!allowed) {
+    context.status = 403
+    return
+  }
+
+  const refs = String(context.query.refs ?? '')
+    .split(',')
+    .map(ref => ref.trim())
+    .filter(Boolean)
+
+  try {
+    const { name, bytes } = await figurePackageOf({
+      refs,
+      domain,
+      exportedBy: user?.email ?? user?.name ?? null,
+      sourceUrl: config.get('figure.publicUrl', context.origin)
+    })
+    context.set('Content-Disposition', `attachment; filename="${name}"`)
+    context.set('Cache-Control', 'private, no-store')
+    context.type = 'application/zip'
+    context.body = bytes
+  } catch (error) {
+    if (!(error instanceof Refusal)) throw error
+    const spoken = speakRefusal(error, { t: (context as any).t })
+    context.status = 400
+    context.body = { code: error.code, params: error.params, message: spoken.message }
+  }
+})

package/server/routes.ts

@@ -2,6 +2,7 @@ import { config } from '@things-factory/env'
 import { getRoutePrefixForDomainType } from '@things-factory/shell'
 
 import { figureThumbnailRouter } from './routers/figure-thumbnail-router.js'
+import { figurePackageRouter } from './routers/figure-package-router.js'
 
 /**
  * 도메인 경로가 주소에 들어가는 배치인가.
@@ -18,7 +19,9 @@ process.on('bootstrap-module-domain-private-route' as any, (app, domainPrivateRo
       figureThumbnailRouter.routes(),
       figureThumbnailRouter.allowedMethods()
     )
+    domainPrivateRouter.use(`/${getRoutePrefixForDomainType()}/:domain`, figurePackageRouter.routes(), figurePackageRouter.allowedMethods())
   } else {
     domainPrivateRouter.use('', figureThumbnailRouter.routes(), figureThumbnailRouter.allowedMethods())
+    domainPrivateRouter.use('', figurePackageRouter.routes(), figurePackageRouter.allowedMethods())
   }
 })

package/server/service/figure/figure-deprecation-db.test.ts

@@ -7,6 +7,7 @@ import type { DataSource } from 'typeorm'
 const { DataSource: TypeOrmDataSource } = require('typeorm')
 const shell = require('@things-factory/shell')
 const authBase = require('@things-factory/auth-base')
+const settingBase = require('@things-factory/setting-base')
 const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy } = require('@hatiolab/figure-model')
 
 let dataSource: DataSource | null = null
@@ -36,7 +37,7 @@ beforeAll(async () => {
     synchronize: true,
     dropSchema: true,
     namingStrategy: new shell.NamingStrategy(),
-    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    entities: [...shell.entities, ...authBase.entities, ...settingBase.entities, Figure, FigureHistory],
     subscribers: [Subscriber],
     logging: false
   })
@@ -48,6 +49,12 @@ afterAll(async () => {
   dataSource = null
 })
 
+/** The domain setting every figure here is created under (ADR-0114). */
+async function namespaced(domain: any) {
+  await dataSource!.getRepository(settingBase.Setting).save({ domain, name: 'figure-namespace', category: 'figure', value: 'system' })
+  return domain
+}
+
 const releasable = () => {
   let a = addFigureBox(createFigureAsset('Mixer'), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
   a = applyFigureAuthoring(a, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
@@ -57,9 +64,9 @@ const releasable = () => {
 let seq = 0
 async function released(type: string) {
   const name = `retire-${++seq}`
-  const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+  const domain = await namespaced(await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name }))
   const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
-  const figure = await dataSource!.getRepository(Figure).save({ type, name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
+  const figure = await dataSource!.getRepository(Figure).save({ namespace: 'system', type, name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
   await new FigureMutation().releaseFigure(figure.id, 'one', context)
   return { figure, context, domain }
 }
@@ -68,7 +75,7 @@ const historyCount = (id: string) => dataSource!.getRepository(FigureHistory).co
 describe('retiring a figure', () => {
   it('stays released, writes no history row, and names what to use instead', async () => {
     const { figure, context, domain } = await released('OLD_MIXER')
-    await dataSource!.getRepository(Figure).save({ type: 'NEW_MIXER', name: 'new', source: releasable(), state: 'draft', version: 0, domain })
+    await dataSource!.getRepository(Figure).save({ namespace: 'system', type: 'NEW_MIXER', name: 'new', source: releasable(), state: 'draft', version: 0, domain })
     const retired = await new FigureMutation().setFigureDeprecation(figure.id, true, context, 'NEW_MIXER')
     expect([retired.deprecated, retired.supersededBy, retired.state, retired.version]).toEqual([true, 'NEW_MIXER', 'released', 1])
     expect(await historyCount(figure.id)).toBe(1)
@@ -95,9 +102,9 @@ describe('names by language', () => {
 
   it('kept on the figure and copied onto the release it goes out with', async () => {
     const name = `names-${++seq}`
-    const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+    const domain = await namespaced(await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name }))
     const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
-    const figure = await dataSource!.getRepository(Figure).save({ type: 'NAMED', name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
+    const figure = await dataSource!.getRepository(Figure).save({ namespace: 'system', type: 'NAMED', name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
     await new FigureMutation().updateFigure(figure.id, { names: { en: 'Mixer', ko: '믹서' } }, context)
     await new FigureMutation().releaseFigure(figure.id, 'one', context)
     const [row] = await dataSource!.getRepository(FigureHistory).find({ where: { originalId: figure.id } })

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

@@ -48,6 +48,10 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({ nullable: true, description: 'The stored identifier of the figure. It never changes.' })
   type?: string
 
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Namespace of the full name {namespace}/{type} at this version.' })
+  namespace?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'The display name at this version.' })
   name?: string

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

@@ -1,8 +1,8 @@
 import { In } from 'typeorm'
-import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
+import { Arg, Ctx, Directive, Mutation, Resolver, UseMiddleware } from 'type-graphql'
 
-import { parseFigureAsset, placeholderType } from '@hatiolab/figure-model'
-import { getRepository } from '@things-factory/shell'
+import { isFigureType, parseFigureAsset, placeholderType, TYPE_LENGTH } from '@hatiolab/figure-model'
+import { getRepository, Refusal, SpeakRefusals } from '@things-factory/shell'
 
 import { Figure } from './figure.js'
 import { FigureHistory } from './figure-history.js'
@@ -13,6 +13,7 @@ import { recordProposals } from './figure-proposal.js'
 import { FigureProposal, ProposeRequest } from './figure-propose-type.js'
 import { inspectSource, releaseRecordOf } from './figure-format.js'
 import { renameDraftType, renameFacts } from './figure-rename.js'
+import { namespaceForNewFigure, namespaceOf } from './figure-namespace.js'
 import { parseSource } from './figure-format.js'
 import { ProposeFigureFailure, proposeFigureSteps } from './figure-propose-steps.js'
 import { prepareFigureWrite, compareAndSwapFigure, pictureOf } from './figure-write.js'
@@ -27,6 +28,7 @@ export function assertNames(names: unknown): asserts names is Record<string, str
 }
 
 @Resolver(Figure)
+@UseMiddleware(SpeakRefusals)
 export class FigureMutation {
   @Directive('@transaction')
   @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
@@ -82,6 +84,7 @@ export class FigureMutation {
         name or not at all -- a taken name refuses the save, rather than saving under the temporary one and failing a
         rename after. Without a name (a caller that has none to give) it is the temporary one, renamed later.
       */
+      const namespace = await namespaceForNewFigure(tx, domain)
       const named = type?.trim()
       if (named) {
         const facts = await renameFacts(
@@ -93,7 +96,7 @@ export class FigureMutation {
         renameDraftType({ type: named, source: prepared.source }, named, facts)
       }
       // insert, not save: a concurrent retry must never turn into an unchecked overwrite.
-      await repository.insert({ ...prepared, id: creationId, type: named || placeholderType(),
+      await repository.insert({ ...prepared, id: creationId, type: named || placeholderType(), namespace,
         domain, creator: user, updater: user })
       return repository.findOneOrFail({ where: { id: creationId, domain: { id: domain.id } } })
     }
@@ -118,6 +121,15 @@ export class FigureMutation {
     const { domain, user, tx } = context.state
     const repository = tx.getRepository(Figure)
 
+    if (!isFigureType(figure.type ?? '')) {
+      throw new Refusal(
+        'figure-type-malformed',
+        { type: figure.type ?? '', min: TYPE_LENGTH.min, max: TYPE_LENGTH.max },
+        '{type} is not a figure type. use lower-case letters, digits and single hyphens, {min} to {max} characters, starting with a letter.'
+      )
+    }
+    const namespace = await namespaceForNewFigure(tx, domain)
+
     // 타입 이름은 도메인 안에서 유일하다. 유니크 인덱스가 있지만 여기서 먼저 본다 —
     // DB 오류 문구는 저작자에게 아무 말도 해 주지 못한다.
     const taken = await repository.findOne({ where: { domain: { id: domain.id }, type: figure.type } })
@@ -133,6 +145,7 @@ export class FigureMutation {
       ...rest,
       source,
       ...derived,
+      namespace,
       state: figure.state ?? 'draft',
       ...(await pictureOf(tx, domain, user, thumbnail)),
       domain,
@@ -303,6 +316,17 @@ export class FigureMutation {
       throw new Error(`Figure '${figure.type}' 은 이미 발행되어 있다. 고쳐서 다시 내려면 초안으로 되돌린 뒤 발행한다`)
     }
 
+    /* A release promises boards the full name {namespace}/{type}; it is refused while the domain setting disagrees. */
+    const namespace = namespaceOf(figure)
+    const current = await namespaceForNewFigure(tx, domain)
+    if (current !== namespace) {
+      throw new Refusal(
+        'figure-namespace-changed',
+        { setting: 'figure-namespace', value: current, namespace },
+        'the figure namespace of this domain is {namespace} and cannot change. set {setting} back to {namespace}.'
+      )
+    }
+
     /*
       ── 게이트는 여기 있어야 한다 ────────────────────────────────────────────
       화면도 같은 판정을 미리 물어(`inspectFigure`) 이유를 보여 주지만, **막는 자리는 이곳뿐이다.**

package/server/service/figure/figure-namespace-db.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Full figure names on the authoring server (ADR-0114): the namespace a figure is created under, the batch door
+ * `figureBlueprints`, and the package a board server imports. sqlite, history subscriber on.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const { createHash } = require('crypto')
+const JSZip = require('jszip')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const settingBase = require('@things-factory/setting-base')
+const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy, readFigurePackage } = require('@hatiolab/figure-model')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureMutation: any
+let FigureQuery: any
+let figurePackageOf: any
+
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', `${modulePath}.js`)
+  if (!existsSync(resolved))
+    throw new Error(`figure-service 산출물이 없다: ${resolved}\n먼저 빌드할 것:\n  yarn workspace @things-factory/figure-service build:server`)
+  return require(resolved)
+}
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  const FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  const Subscriber = loadCompiled('service/figure/event-subscriber').FigureHistoryEntitySubscriber
+  ;({ FigureMutation } = loadCompiled('service/figure/figure-mutation'))
+  ;({ FigureQuery } = loadCompiled('service/figure/figure-query'))
+  ;({ figurePackageOf } = loadCompiled('service/figure/figure-package-export'))
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, ...settingBase.entities, Figure, FigureHistory],
+    subscribers: [Subscriber],
+    logging: false
+  })
+  await dataSource.initialize()
+  shell.addDataSource('default', dataSource)
+  shell.addDataSource('tx', dataSource)
+})
+
+afterAll(async () => {
+  await dataSource?.destroy()
+  dataSource = null
+})
+
+const releasable = (label = 'Conveyor') => {
+  let a = addFigureBox(createFigureAsset(label), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
+  return serializeFigureAsset(applyFigureAuthoring(a, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(a, { over: 'range' }), placement: 'floor' }))
+}
+
+let seq = 0
+async function domainWith(namespace: string | null) {
+  const name = `ns-${++seq}`
+  const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+  if (namespace !== null) {
+    await dataSource!.getRepository(settingBase.Setting).save({ domain, name: 'figure-namespace', category: 'figure', value: namespace })
+  }
+  const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+  return { domain, context }
+}
+
+const creationId = () => require('crypto').randomUUID()
+const setNamespace = (domain: any, value: string) =>
+  dataSource!.getRepository(settingBase.Setting).update({ domain: { id: domain.id }, name: 'figure-namespace' }, { value })
+
+async function releasedFigure(context: any, type: string) {
+  const figure = await new FigureMutation().saveFigure(releasable(type), context, undefined, undefined, creationId(), undefined, type)
+  await new FigureMutation().releaseFigure(figure.id, 'first', context)
+  return figure
+}
+
+describe('the namespace a figure is created under', () => {
+  it('is copied from the domain setting onto a new figure', async () => {
+    const { context } = await domainWith('hatiolab.com')
+    const figure = await new FigureMutation().saveFigure(releasable(), context, undefined, undefined, creationId(), undefined, 'conveyor')
+    expect(figure.namespace).toBe('hatiolab.com')
+    expect(figure.type).toBe('conveyor')
+  })
+
+  it('is refused by name when the domain has none, or an invalid one', async () => {
+    for (const value of [null, 'Hatiolab.COM']) {
+      const { context } = await domainWith(value)
+      await expect(
+        new FigureMutation().saveFigure(releasable(), context, undefined, undefined, creationId(), undefined, 'conveyor')
+      ).rejects.toMatchObject({ code: 'figure-namespace-missing' })
+    }
+  })
+
+  it('cannot change: a new figure or a release is refused while the setting disagrees with the figures already made', async () => {
+    const { domain, context } = await domainWith('hatiolab.com')
+    const draft = await new FigureMutation().saveFigure(releasable(), context, undefined, undefined, creationId(), undefined, 'conveyor')
+    await setNamespace(domain, 'other.com')
+    await expect(
+      new FigureMutation().saveFigure(releasable(), context, undefined, undefined, creationId(), undefined, 'lifter')
+    ).rejects.toMatchObject({ code: 'figure-namespace-changed' })
+    await expect(new FigureMutation().releaseFigure(draft.id, 'c', context)).rejects.toMatchObject({ code: 'figure-namespace-changed' })
+
+    await setNamespace(domain, 'hatiolab.com')
+    await expect(new FigureMutation().releaseFigure(draft.id, 'c', context)).resolves.toMatchObject({ version: 1 })
+  })
+
+  it('refuses an upper-case type when creating directly', async () => {
+    const { context } = await domainWith('hatiolab.com')
+    await expect(
+      new FigureMutation().createFigure({ type: 'CONVEYOR', name: 'c', source: releasable() }, context)
+    ).rejects.toMatchObject({ code: 'figure-type-malformed' })
+  })
+})
+
+describe('figureBlueprints answers each full name, an item or a refusal', () => {
+  it('gives released figures by full name and refuses the rest by cause, none taking another away', async () => {
+    const { context } = await domainWith('hatiolab.com')
+    await releasedFigure(context, 'conveyor')
+    await new FigureMutation().saveFigure(releasable(), context, undefined, undefined, creationId(), undefined, 'draft-only')
+
+    const answer = await new FigureQuery().figureBlueprints(
+      ['hatiolab.com/conveyor', 'hatiolab.com/draft-only', 'other.com/conveyor', 'CONVEYOR', 'hatiolab.com/conveyor'],
+      context
+    )
+
+    expect(answer.release).toBeNull()
+    expect(answer.items.map((item: any) => [item.type, item.ref])).toEqual([['hatiolab.com/conveyor', 'hatiolab.com/conveyor@1']])
+    expect(answer.items[0].asset.version).toBe('figure-asset-1')
+    expect(answer.refused.map((r: any) => [r.type, r.code])).toEqual([
+      ['hatiolab.com/draft-only', 'figure-not-released'],
+      ['other.com/conveyor', 'figure-not-released'],
+      ['CONVEYOR', 'figure-name-malformed']
+    ])
+  })
+})
+
+describe('the figure package', () => {
+  const sha256 = (bytes: Uint8Array) => createHash('sha256').update(bytes).digest('hex')
+
+  it('carries the release a board server reads back whole, and names the server it came from', async () => {
+    const { domain, context } = await domainWith('hatiolab.com')
+    const figure = await releasedFigure(context, 'trailer-22')
+
+    const { name, bytes } = await figurePackageOf({
+      refs: ['hatiolab.com/trailer-22@1'],
+      domain,
+      exportedBy: 'author',
+      sourceUrl: 'https://figure.hatiolab.com',
+      files: { put: async () => ({}), send: async () => {}, read: async () => Buffer.alloc(0) }
+    })
+    expect(name).toBe('hatiolab.com_trailer-22_1.figpkg')
+
+    const zip = await JSZip.loadAsync(bytes)
+    const files = new Map<string, Uint8Array>()
+    for (const path of Object.keys(zip.files)) if (!zip.files[path].dir) files.set(path, await zip.files[path].async('uint8array'))
+    const read = readFigurePackage(files, sha256)
+
+    expect(read.problems).toEqual([])
+    expect(read.refused).toEqual([])
+    expect(read.manifest.source).toEqual({ url: 'https://figure.hatiolab.com', domain: domain.subdomain })
+    expect(read.releases.map((r: any) => r.ref)).toEqual(['hatiolab.com/trailer-22@1'])
+    const stored = await dataSource!.getRepository(Figure).findOneOrFail({ where: { id: figure.id } })
+    expect(read.releases[0].source).toBe(stored.source)
+  })
+
+  it('refuses a release this domain cannot read, and a malformed reference', async () => {
+    const { domain, context } = await domainWith('hatiolab.com')
+    await releasedFigure(context, 'conveyor')
+    const ask = (refs: string[]) => figurePackageOf({ refs, domain, exportedBy: null, sourceUrl: 'x' })
+    await expect(ask(['hatiolab.com/conveyor@2'])).rejects.toMatchObject({ code: 'figure-package-release-not-found' })
+    await expect(ask(['other.com/conveyor@1'])).rejects.toMatchObject({ code: 'figure-package-release-not-found' })
+    await expect(ask(['CONVEYOR@1'])).rejects.toMatchObject({ code: 'figure-ref-malformed' })
+  })
+})