@realsee/vr-cli 0.1.4 → 0.2.0

package/templates/base/scripts/setup-config.mjs

@@ -0,0 +1,252 @@
+import { randomUUID } from 'node:crypto'
+import { chmod, lstat, mkdir, open, rename, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+export const SETUP_PAYLOAD_PREFIX = 'realsee-setup:v1:'
+export const DEFAULT_GATEWAY_ENDPOINT = 'https://app-gateway.realsee.cn'
+
+const RESOURCE_CODE_PATTERN = /^[A-Za-z0-9_-]{1,128}$/
+const GATEWAY_ENDPOINT_PATTERN =
+  /^https:\/\/[A-Za-z0-9.-]+(?::\d+)?(?:\/[A-Za-z0-9._~%/-]*)?$/u
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/
+const MAX_PAYLOAD_LENGTH = 8_192
+const MAX_CREDENTIAL_LENGTH = 1_024
+
+function setupError(message) {
+  return new Error(`配置包无效：${message}`)
+}
+
+function credentialError(message) {
+  return new Error(`网关凭证无效：${message}`)
+}
+
+function exactString(value, label, makeError = setupError) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.length > MAX_CREDENTIAL_LENGTH ||
+    value !== value.trim() ||
+    /[\0\r\n]/u.test(value)
+  ) {
+    throw makeError(`${label} 缺失或格式不正确。`)
+  }
+  return value
+}
+
+// Normalizes credentials resolved outside the pasted payload (environment
+// variables and the pairing protocol) into the exact shape the writer renders.
+export function normalizeGatewayCredentials({
+  appKey,
+  appSecret,
+  resourceCode,
+  gatewayEndpoint,
+}) {
+  const config = {
+    appKey: exactString(appKey, 'AK', credentialError),
+    appSecret: exactString(appSecret, 'SK', credentialError),
+  }
+  if (resourceCode !== undefined && resourceCode !== '') {
+    const value = exactString(resourceCode, 'resourceCode', credentialError)
+    if (!RESOURCE_CODE_PATTERN.test(value)) {
+      throw credentialError('resourceCode 格式不正确。')
+    }
+    config.resourceCode = value
+  }
+  if (gatewayEndpoint !== undefined && gatewayEndpoint !== '') {
+    const value = exactString(
+      gatewayEndpoint,
+      'gatewayEndpoint',
+      credentialError,
+    )
+    if (!GATEWAY_ENDPOINT_PATTERN.test(value)) {
+      throw credentialError('gatewayEndpoint 必须是 HTTPS URL。')
+    }
+    config.gatewayEndpoint = value
+  }
+  return Object.freeze(config)
+}
+
+export function decodeSetupPayload(input) {
+  const value = typeof input === 'string' ? input.trim() : ''
+  if (!value.startsWith(SETUP_PAYLOAD_PREFIX)) {
+    throw setupError('请从 Portal 复制完整的 v1 本地配置。')
+  }
+
+  const encoded = value.slice(SETUP_PAYLOAD_PREFIX.length)
+  if (
+    encoded.length === 0 ||
+    encoded.length > MAX_PAYLOAD_LENGTH ||
+    !BASE64URL_PATTERN.test(encoded)
+  ) {
+    throw setupError('单行内容损坏或不完整。')
+  }
+
+  let text
+  try {
+    const bytes = Buffer.from(encoded, 'base64url')
+    if (bytes.toString('base64url') !== encoded) {
+      throw setupError('Base64URL 内容不是规范编码。')
+    }
+    text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  } catch {
+    throw setupError('Base64URL 内容无法解码。')
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw setupError('JSON 内容无法解析。')
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw setupError('内容结构不正确。')
+  }
+  const keys = Object.keys(parsed).sort()
+  const keyList = keys.join(',')
+  if (
+    keyList !== 'appKey,appSecret' &&
+    keyList !== 'appKey,appSecret,resourceCode'
+  ) {
+    throw setupError('字段集合不正确。')
+  }
+
+  const appKey = exactString(parsed.appKey, 'AK')
+  const appSecret = exactString(parsed.appSecret, 'SK')
+  let resourceCode
+  if (parsed.resourceCode !== undefined && parsed.resourceCode !== '') {
+    resourceCode = exactString(parsed.resourceCode, 'resourceCode')
+    if (!RESOURCE_CODE_PATTERN.test(resourceCode)) {
+      throw setupError('resourceCode 格式不正确。')
+    }
+  }
+
+  return Object.freeze({
+    appKey,
+    appSecret,
+    ...(resourceCode === undefined ? {} : { resourceCode }),
+  })
+}
+
+function quoteDotenvValue(value) {
+  return JSON.stringify(value)
+}
+
+export function renderLocalEnv({
+  appKey,
+  appSecret,
+  resourceCode,
+  gatewayEndpoint,
+}) {
+  return [
+    '# Generated by npm run setup. Keep this server-only file out of version control.',
+    `REALSEE_GATEWAY_ENDPOINT=${gatewayEndpoint ?? DEFAULT_GATEWAY_ENDPOINT}`,
+    `REALSEE_GATEWAY_APP_KEY=${quoteDotenvValue(appKey)}`,
+    `REALSEE_GATEWAY_APP_SECRET=${quoteDotenvValue(appSecret)}`,
+    ...(resourceCode
+      ? [`REALSEE_DEFAULT_RESOURCE_CODE=${quoteDotenvValue(resourceCode)}`]
+      : []),
+    '',
+  ].join('\n')
+}
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      shell: false,
+      stdio: 'ignore',
+      windowsHide: true,
+    })
+    child.once('error', reject)
+    child.once('exit', (code) => {
+      if (code === 0) resolve()
+      else reject(new Error(`${command} exited with code ${code ?? 'unknown'}`))
+    })
+  })
+}
+
+function windowsIdentity(env) {
+  const username = env.USERNAME?.trim() || os.userInfo().username
+  const domain = env.USERDOMAIN?.trim()
+  return domain ? `${domain}\\${username}` : username
+}
+
+export async function protectLocalConfig(
+  targetPath,
+  { platform = process.platform, env = process.env, runCommand = run } = {},
+) {
+  if (platform === 'win32') {
+    const identity = windowsIdentity(env)
+    await runCommand('icacls.exe', [
+      targetPath,
+      '/inheritance:r',
+      '/grant:r',
+      `${identity}:(F)`,
+    ])
+    return
+  }
+  await chmod(targetPath, 0o600)
+}
+
+async function assertSafeTarget(targetPath) {
+  try {
+    const target = await lstat(targetPath)
+    if (!target.isFile() || target.isSymbolicLink()) {
+      throw new Error('.env.development 必须是普通文件。')
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+}
+
+// Shared atomic write chain: restrictive umask, exclusive 0600 temp file,
+// fsync, platform permission hardening, then rename into place. Used for
+// `.env.development` and for the 0600 pairing continuation file.
+export async function writePrivateFile(
+  targetPath,
+  content,
+  { platform = process.platform, env = process.env, runCommand = run } = {},
+) {
+  await mkdir(path.dirname(targetPath), { recursive: true, mode: 0o700 })
+  const temporaryPath = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`,
+  )
+  const previousUmask = platform === 'win32' ? undefined : process.umask(0o077)
+
+  try {
+    const handle = await open(temporaryPath, 'wx', 0o600)
+    try {
+      await handle.writeFile(content, 'utf8')
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    await protectLocalConfig(temporaryPath, { platform, env, runCommand })
+    await rename(temporaryPath, targetPath)
+    return targetPath
+  } finally {
+    if (previousUmask !== undefined) process.umask(previousUmask)
+    await rm(temporaryPath, { force: true }).catch(() => undefined)
+  }
+}
+
+export async function writeLocalConfig(
+  config,
+  {
+    root = process.cwd(),
+    platform = process.platform,
+    env = process.env,
+    runCommand = run,
+  } = {},
+) {
+  const targetPath = path.join(path.resolve(root), '.env.development')
+  await assertSafeTarget(targetPath)
+  return writePrivateFile(targetPath, renderLocalEnv(config), {
+    platform,
+    env,
+    runCommand,
+  })
+}

package/templates/base/scripts/setup-config.test.mjs

@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+import {
+  decodeSetupPayload,
+  protectLocalConfig,
+  renderLocalEnv,
+  SETUP_PAYLOAD_PREFIX,
+  writeLocalConfig,
+} from './setup-config.mjs'
+
+const CONFIG = Object.freeze({
+  appKey: 'test-app-key',
+  appSecret: '测试-secret_+/=',
+  resourceCode: 'resource-code_1',
+})
+const CONFIG_WITHOUT_RESOURCE = Object.freeze({
+  appKey: CONFIG.appKey,
+  appSecret: CONFIG.appSecret,
+})
+
+const ENCODED =
+  'eyJhcHBLZXkiOiJ0ZXN0LWFwcC1rZXkiLCJhcHBTZWNyZXQiOiLmtYvor5Utc2VjcmV0XysvPSIsInJlc291cmNlQ29kZSI6InJlc291cmNlLWNvZGVfMSJ9'
+const encode = (value) =>
+  Buffer.from(JSON.stringify(value)).toString('base64url')
+
+test('decodes the existing versioned payload with its optional resource fallback', () => {
+  assert.deepEqual(
+    decodeSetupPayload(`${SETUP_PAYLOAD_PREFIX}${ENCODED}`),
+    CONFIG,
+  )
+})
+
+test('accepts a v1 setup payload without a resource fallback', () => {
+  assert.deepEqual(
+    decodeSetupPayload(
+      `${SETUP_PAYLOAD_PREFIX}${encode(CONFIG_WITHOUT_RESOURCE)}`,
+    ),
+    CONFIG_WITHOUT_RESOURCE,
+  )
+  assert.deepEqual(
+    decodeSetupPayload(
+      `${SETUP_PAYLOAD_PREFIX}${encode({ ...CONFIG_WITHOUT_RESOURCE, resourceCode: '' })}`,
+    ),
+    CONFIG_WITHOUT_RESOURCE,
+  )
+})
+
+test('rejects non-canonical, malformed and extra-field payloads', () => {
+  assert.throws(() => decodeSetupPayload('not-a-setup-payload'))
+  assert.throws(() => decodeSetupPayload(`${SETUP_PAYLOAD_PREFIX}${ENCODED}=`))
+  assert.throws(() =>
+    decodeSetupPayload(
+      `${SETUP_PAYLOAD_PREFIX}${encode({ appKey: CONFIG.appKey })}`,
+    ),
+  )
+  assert.throws(() =>
+    decodeSetupPayload(
+      `${SETUP_PAYLOAD_PREFIX}${encode({ ...CONFIG, resourceCode: 'invalid code' })}`,
+    ),
+  )
+  assert.throws(() =>
+    decodeSetupPayload(
+      `${SETUP_PAYLOAD_PREFIX}${encode({ ...CONFIG, unexpected: true })}`,
+    ),
+  )
+})
+
+test('renders the optional fallback only when it is configured', () => {
+  const rendered = renderLocalEnv(CONFIG)
+  assert.match(
+    rendered,
+    /REALSEE_GATEWAY_ENDPOINT=https:\/\/app-gateway\.realsee\.cn/u,
+  )
+  assert.match(rendered, /REALSEE_GATEWAY_APP_KEY="test-app-key"/u)
+  assert.match(rendered, /REALSEE_GATEWAY_APP_SECRET="测试-secret_\+\/="/u)
+  assert.match(rendered, /REALSEE_DEFAULT_RESOURCE_CODE="resource-code_1"/u)
+  assert.doesNotMatch(rendered, /realsee-setup:v1:/u)
+
+  const withoutResource = renderLocalEnv(CONFIG_WITHOUT_RESOURCE)
+  assert.match(withoutResource, /REALSEE_GATEWAY_APP_KEY="test-app-key"/u)
+  assert.doesNotMatch(withoutResource, /REALSEE_DEFAULT_RESOURCE_CODE/u)
+})
+
+test('writes atomically with restrictive POSIX permissions', async () => {
+  if (process.platform === 'win32') return
+  const root = await mkdtemp(path.join(os.tmpdir(), 'realsee-setup-'))
+  try {
+    const target = await writeLocalConfig(CONFIG_WITHOUT_RESOURCE, {
+      root,
+      platform: 'linux',
+    })
+    assert.equal(
+      await readFile(target, 'utf8'),
+      renderLocalEnv(CONFIG_WITHOUT_RESOURCE),
+    )
+    assert.equal((await stat(target)).mode & 0o777, 0o600)
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('uses icacls without a shell for Windows ACL protection', async () => {
+  const calls = []
+  await protectLocalConfig('C:\\project\\.env.development', {
+    platform: 'win32',
+    env: { USERDOMAIN: 'WORKSTATION', USERNAME: 'developer' },
+    runCommand: async (command, args) => calls.push({ command, args }),
+  })
+  assert.deepEqual(calls, [
+    {
+      command: 'icacls.exe',
+      args: [
+        'C:\\project\\.env.development',
+        '/inheritance:r',
+        '/grant:r',
+        'WORKSTATION\\developer:(F)',
+      ],
+    },
+  ])
+})

package/templates/base/scripts/setup.mjs

@@ -0,0 +1,203 @@
+import { pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
+import { Writable } from 'node:stream'
+import { createInterface } from 'node:readline/promises'
+import {
+  decodeSetupPayload,
+  normalizeGatewayCredentials,
+  writeLocalConfig,
+} from './setup-config.mjs'
+import {
+  PAIRING_EXIT_CODES,
+  maskAppKey,
+  reportPairingFailure,
+  runPairingCommand,
+  runPairingCompleteCommand,
+} from './pairing.mjs'
+
+const HELP = `用法：npm run setup [-- <选项>]
+
+默认走配对：发起请求，打印验证链接与短码，阻塞轮询到终态并写入 .env.development。
+  --pair       显式选择配对路径（默认行为）。
+  --no-wait    发起后立即退出（退出码 2），稍后用 --complete 续做。
+  --complete   读取 .realsee/pairing-continuation.json，轮询到终态并写入。
+  --paste      回退路径：把 Portal 复制的单行配置包粘贴到隐藏输入。
+  --json       只输出 JSON 信封，不打印人类可读提示。
+  -h, --help   显示本帮助。
+
+环境变量 REALSEE_GATEWAY_APP_KEY / REALSEE_GATEWAY_APP_SECRET 优先级最高，
+设置后跳过配对，直接写入 .env.development。
+`
+
+class HiddenOutput extends Writable {
+  _write(_chunk, _encoding, callback) {
+    callback()
+  }
+}
+
+async function readHiddenPayload() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      'npm run setup 需要交互终端。请勿通过参数、管道、重定向或聊天传入配置包。',
+    )
+  }
+
+  process.stdout.write(
+    '请在 Portal 点击“复制本地配置”，粘贴到这里并按 Enter（输入不会显示）：',
+  )
+  const controller = new AbortController()
+  const input = process.stdin
+  const output = new HiddenOutput()
+  const prompt = createInterface({ input, output, terminal: true })
+  prompt.once('SIGINT', () => controller.abort())
+  try {
+    const value = await prompt.question('', { signal: controller.signal })
+    process.stdout.write('\n')
+    return value
+  } finally {
+    prompt.close()
+  }
+}
+
+async function runPasteFlow() {
+  const payload = decodeSetupPayload(await readHiddenPayload())
+  await writeLocalConfig(payload)
+  console.log('配置完成。请回到 AI 助手并回复“已完成”。')
+}
+
+function parseSetupArguments(argv) {
+  try {
+    return parseArgs({
+      args: argv,
+      allowPositionals: false,
+      strict: true,
+      options: {
+        pair: { type: 'boolean', default: false },
+        paste: { type: 'boolean', default: false },
+        complete: { type: 'boolean', default: false },
+        'no-wait': { type: 'boolean', default: false },
+        json: { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    }).values
+  } catch (error) {
+    throw new Error(
+      `参数错误：${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    )
+  }
+}
+
+function resolveMode(values) {
+  if (values.paste) {
+    const conflicting = ['pair', 'complete', 'no-wait', 'json'].find(
+      (flag) => values[flag] === true,
+    )
+    if (conflicting) {
+      throw new Error(`--paste 不能与 --${conflicting} 同时使用。`)
+    }
+    return 'paste'
+  }
+  if (values.complete) {
+    if (values['no-wait']) {
+      throw new Error('--complete 不能与 --no-wait 同时使用。')
+    }
+    return 'complete'
+  }
+  return 'pair'
+}
+
+function environmentCredentials(env = process.env) {
+  const appKey = env.REALSEE_GATEWAY_APP_KEY?.trim()
+  const appSecret = env.REALSEE_GATEWAY_APP_SECRET?.trim()
+  if (!appKey && !appSecret) return null
+  if (!appKey || !appSecret) {
+    throw new Error(
+      'REALSEE_GATEWAY_APP_KEY 与 REALSEE_GATEWAY_APP_SECRET 必须同时提供。',
+    )
+  }
+  const resourceCode = env.REALSEE_DEFAULT_RESOURCE_CODE?.trim()
+  const gatewayEndpoint = env.REALSEE_GATEWAY_ENDPOINT?.trim()
+  return normalizeGatewayCredentials({
+    appKey,
+    appSecret,
+    ...(resourceCode ? { resourceCode } : {}),
+    ...(gatewayEndpoint ? { gatewayEndpoint } : {}),
+  })
+}
+
+async function configureFromEnvironment(config, { json }) {
+  await writeLocalConfig(config)
+  if (json !== true) {
+    process.stderr.write(
+      '检测到 REALSEE_GATEWAY_APP_KEY / REALSEE_GATEWAY_APP_SECRET 环境变量（优先级最高），已跳过配对并写入 .env.development。\n',
+    )
+  }
+  process.stdout.write(
+    `${JSON.stringify({
+      ok: true,
+      data: {
+        status: 'configured',
+        source: 'environment',
+        app_key: maskAppKey(config.appKey),
+        path: '.env.development',
+      },
+    })}\n`,
+  )
+  return PAIRING_EXIT_CODES.OK
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  let values
+  try {
+    values = parseSetupArguments(argv)
+  } catch (error) {
+    return reportPairingFailure(error, { json: false })
+  }
+
+  if (values.help) {
+    process.stdout.write(HELP)
+    return PAIRING_EXIT_CODES.OK
+  }
+
+  let mode
+  try {
+    mode = resolveMode(values)
+  } catch (error) {
+    return reportPairingFailure(error, { json: values.json === true })
+  }
+
+  // The paste fallback keeps its original interactive behaviour.
+  if (mode === 'paste') {
+    await runPasteFlow()
+    return PAIRING_EXIT_CODES.OK
+  }
+
+  const json = values.json === true
+  try {
+    const config = environmentCredentials()
+    if (config) return await configureFromEnvironment(config, { json })
+  } catch (error) {
+    return reportPairingFailure(error, { json })
+  }
+
+  if (mode === 'complete') {
+    return await runPairingCompleteCommand({ json })
+  }
+  return await runPairingCommand({ noWait: values['no-wait'] === true, json })
+}
+
+const entrypoint = process.argv[1]
+if (entrypoint && import.meta.url === pathToFileURL(entrypoint).href) {
+  main()
+    .then((exitCode) => {
+      if (typeof exitCode === 'number' && exitCode !== 0) {
+        process.exitCode = exitCode
+      }
+    })
+    .catch((error) => {
+      const message = error instanceof Error ? error.message : '未知错误。'
+      console.error(`本地配置失败：${message}`)
+      process.exitCode = 1
+    })
+}

package/templates/base/server/app.ts

@@ -9,6 +9,7 @@ const PROJECT_ROOT = fileURLToPath(new URL('..', import.meta.url))
 
 export interface CreateAppOptions {
   readonly workService: WorkService
+  readonly defaultResourceCode: string | undefined
   readonly logger?: boolean
   readonly serveFrontend?: boolean
   readonly frontendRoot?: string
@@ -16,6 +17,7 @@ export interface CreateAppOptions {
 
 export async function createApp({
   workService,
+  defaultResourceCode,
   logger = true,
   serveFrontend = false,
   frontendRoot = path.join(PROJECT_ROOT, 'dist'),
@@ -23,7 +25,7 @@ export async function createApp({
   const app = Fastify({ logger })
 
   app.get('/api/health', () => ({ ok: true }))
-  await app.register(workRoutes, { workService })
+  await app.register(workRoutes, { workService, defaultResourceCode })
 
   if (serveFrontend) {
     await app.register(fastifyStatic, {

package/templates/base/server/config.ts

@@ -1,6 +1,7 @@
 import type { ServerConfig } from './types.ts'
 
 const DEFAULT_GATEWAY_ENDPOINT = 'https://app-gateway.realsee.cn'
+const RESOURCE_CODE_PATTERN = /^[A-Za-z0-9_-]{1,128}$/
 
 type ServerEnv = Record<string, string | undefined>
 
@@ -15,8 +16,17 @@ const nonEmptyString = (value: string | undefined): value is string =>
 function requiredCredential(env: ServerEnv, key: string): string {
   const value = env[key]?.trim()
   if (!nonEmptyString(value) || value === '*') {
+    throw new Error(`${key} 未配置。请运行 npm run setup 完成本地配置。`)
+  }
+  return value
+}
+
+function optionalResourceCode(env: ServerEnv): string | undefined {
+  const value = env.REALSEE_DEFAULT_RESOURCE_CODE?.trim()
+  if (!nonEmptyString(value)) return undefined
+  if (!RESOURCE_CODE_PATTERN.test(value)) {
     throw new Error(
-      `${key} 未配置。请从 .env.example 创建 .env.development，并填写服务端凭据。`,
+      'REALSEE_DEFAULT_RESOURCE_CODE 格式无效，必须匹配 ^[A-Za-z0-9_-]{1,128}$。',
     )
   }
   return value
@@ -50,5 +60,6 @@ export function loadServerConfig({
     gatewayEndpoint: gatewayEndpoint.href.replace(/\/$/, ''),
     appKey: requiredCredential(env, 'REALSEE_GATEWAY_APP_KEY'),
     appSecret: requiredCredential(env, 'REALSEE_GATEWAY_APP_SECRET'),
+    defaultResourceCode: optionalResourceCode(env),
   })
 }

package/templates/base/server/index.ts

@@ -7,7 +7,11 @@ const serveFrontend = process.argv.includes('--serve-frontend')
 const config = loadServerConfig({ serveFrontend })
 const openApiClient = new RealseeOpenApiClient(config)
 const workService = createWorkService({ openApiClient })
-const app = await createApp({ workService, serveFrontend })
+const app = await createApp({
+  workService,
+  defaultResourceCode: config.defaultResourceCode,
+  serveFrontend,
+})
 
 let closing = false
 const close = async (signal: string): Promise<void> => {

package/templates/base/server/types.ts

@@ -11,6 +11,7 @@ export interface ServerConfig {
   readonly gatewayEndpoint: string
   readonly appKey: string
   readonly appSecret: string
+  readonly defaultResourceCode: string | undefined
 }
 
 export interface RequestOptions {
@@ -21,7 +22,7 @@ export interface WorkCapabilities {
   readonly modelFloorplan?: ModelFloorplanServerData
 }
 
-/** Browser-safe response envelope for `GET /api/work/{resourceCode}`. */
+/** Browser-safe response envelope for `GET /api/work`. */
 export interface WorkEnvelope {
   readonly work: RawRecord
   readonly workCode: string