@realsee/vr-cli 0.1.5 → 0.2.1

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

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto'
-import { chmod, lstat, open, rename, rm } from 'node:fs/promises'
+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'
@@ -8,6 +8,8 @@ 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
@@ -16,7 +18,11 @@ function setupError(message) {
   return new Error(`配置包无效：${message}`)
 }
 
-function exactString(value, label) {
+function credentialError(message) {
+  return new Error(`网关凭证无效：${message}`)
+}
+
+function exactString(value, label, makeError = setupError) {
   if (
     typeof value !== 'string' ||
     value.length === 0 ||
@@ -24,11 +30,44 @@ function exactString(value, label) {
     value !== value.trim() ||
     /[\0\r\n]/u.test(value)
   ) {
-    throw setupError(`${label} 缺失或格式不正确。`)
+    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)) {
@@ -66,31 +105,49 @@ export function decodeSetupPayload(input) {
     throw setupError('内容结构不正确。')
   }
   const keys = Object.keys(parsed).sort()
-  if (keys.join(',') !== 'appKey,appSecret,resourceCode') {
+  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')
-  const resourceCode = exactString(parsed.resourceCode, 'resourceCode')
-  if (!RESOURCE_CODE_PATTERN.test(resourceCode)) {
-    throw setupError('resourceCode 格式不正确。')
+  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 })
+  return Object.freeze({
+    appKey,
+    appSecret,
+    ...(resourceCode === undefined ? {} : { resourceCode }),
+  })
 }
 
 function quoteDotenvValue(value) {
   return JSON.stringify(value)
 }
 
-export function renderLocalEnv({ appKey, appSecret, resourceCode }) {
+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=${DEFAULT_GATEWAY_ENDPOINT}`,
+    `REALSEE_GATEWAY_ENDPOINT=${gatewayEndpoint ?? DEFAULT_GATEWAY_ENDPOINT}`,
     `REALSEE_GATEWAY_APP_KEY=${quoteDotenvValue(appKey)}`,
     `REALSEE_GATEWAY_APP_SECRET=${quoteDotenvValue(appSecret)}`,
-    `REALSEE_DEFAULT_RESOURCE_CODE=${quoteDotenvValue(resourceCode)}`,
+    ...(resourceCode
+      ? [`REALSEE_DEFAULT_RESOURCE_CODE=${quoteDotenvValue(resourceCode)}`]
+      : []),
     '',
   ].join('\n')
 }
@@ -144,27 +201,25 @@ async function assertSafeTarget(targetPath) {
   }
 }
 
-export async function writeLocalConfig(
-  config,
-  {
-    root = process.cwd(),
-    platform = process.platform,
-    env = process.env,
-    runCommand = run,
-  } = {},
+// 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 } = {},
 ) {
-  const targetPath = path.join(path.resolve(root), '.env.development')
-  await assertSafeTarget(targetPath)
+  await mkdir(path.dirname(targetPath), { recursive: true, mode: 0o700 })
   const temporaryPath = path.join(
     path.dirname(targetPath),
-    `.env.development.${process.pid}.${randomUUID()}.tmp`,
+    `.${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(renderLocalEnv(config), 'utf8')
+      await handle.writeFile(content, 'utf8')
       await handle.sync()
     } finally {
       await handle.close()
@@ -177,3 +232,21 @@ export async function writeLocalConfig(
     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

@@ -16,29 +16,59 @@ const CONFIG = Object.freeze({
   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 versioned UTF-8 Base64URL setup payload', () => {
+test('decodes the existing versioned payload with its optional resource fallback', () => {
   assert.deepEqual(
     decodeSetupPayload(`${SETUP_PAYLOAD_PREFIX}${ENCODED}`),
     CONFIG,
   )
 })
 
-test('rejects non-canonical, incomplete and extra-field payloads', () => {
+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}=`))
-  const withExtraField = Buffer.from(
-    JSON.stringify({ ...CONFIG, unexpected: true }),
-  ).toString('base64url')
   assert.throws(() =>
-    decodeSetupPayload(`${SETUP_PAYLOAD_PREFIX}${withExtraField}`),
+    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 one server-only env file without printing the setup payload', () => {
+test('renders the optional fallback only when it is configured', () => {
   const rendered = renderLocalEnv(CONFIG)
   assert.match(
     rendered,
@@ -48,14 +78,24 @@ test('renders one server-only env file without printing the setup payload', () =
   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, { root, platform: 'linux' })
-    assert.equal(await readFile(target, 'utf8'), renderLocalEnv(CONFIG))
+    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 })

package/templates/base/scripts/setup.mjs

@@ -1,7 +1,33 @@
 import { pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
 import { Writable } from 'node:stream'
 import { createInterface } from 'node:readline/promises'
-import { decodeSetupPayload, writeLocalConfig } from './setup-config.mjs'
+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) {
@@ -33,17 +59,145 @@ async function readHiddenPayload() {
   }
 }
 
-export async function main() {
+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().catch((error) => {
-    const message = error instanceof Error ? error.message : '未知错误。'
-    console.error(`本地配置失败：${message}`)
-    process.exitCode = 1
-  })
+  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,7 +9,7 @@ const PROJECT_ROOT = fileURLToPath(new URL('..', import.meta.url))
 
 export interface CreateAppOptions {
   readonly workService: WorkService
-  readonly defaultResourceCode: string
+  readonly defaultResourceCode: string | undefined
   readonly logger?: boolean
   readonly serveFrontend?: boolean
   readonly frontendRoot?: string

package/templates/base/server/config.ts

@@ -21,11 +21,12 @@ function requiredCredential(env: ServerEnv, key: string): string {
   return value
 }
 
-function requiredResourceCode(env: ServerEnv): string {
+function optionalResourceCode(env: ServerEnv): string | undefined {
   const value = env.REALSEE_DEFAULT_RESOURCE_CODE?.trim()
-  if (!nonEmptyString(value) || !RESOURCE_CODE_PATTERN.test(value)) {
+  if (!nonEmptyString(value)) return undefined
+  if (!RESOURCE_CODE_PATTERN.test(value)) {
     throw new Error(
-      'REALSEE_DEFAULT_RESOURCE_CODE 未配置或格式无效。请运行 npm run setup 完成本地配置。',
+      'REALSEE_DEFAULT_RESOURCE_CODE 格式无效，必须匹配 ^[A-Za-z0-9_-]{1,128}$。',
     )
   }
   return value
@@ -59,6 +60,6 @@ export function loadServerConfig({
     gatewayEndpoint: gatewayEndpoint.href.replace(/\/$/, ''),
     appKey: requiredCredential(env, 'REALSEE_GATEWAY_APP_KEY'),
     appSecret: requiredCredential(env, 'REALSEE_GATEWAY_APP_SECRET'),
-    defaultResourceCode: requiredResourceCode(env),
+    defaultResourceCode: optionalResourceCode(env),
   })
 }

package/templates/base/server/types.ts

@@ -11,7 +11,7 @@ export interface ServerConfig {
   readonly gatewayEndpoint: string
   readonly appKey: string
   readonly appSecret: string
-  readonly defaultResourceCode: string
+  readonly defaultResourceCode: string | undefined
 }
 
 export interface RequestOptions {

package/templates/base/server/work-route.ts

@@ -5,7 +5,7 @@ const RESOURCE_CODE_PATTERN = '^[A-Za-z0-9_-]{1,128}$'
 
 export interface WorkRoutesOptions {
   readonly workService: WorkService
-  readonly defaultResourceCode: string
+  readonly defaultResourceCode: string | undefined
 }
 
 interface WorkRouteParams {
@@ -59,8 +59,19 @@ export function workRoutes(
     }
   }
 
-  app.get('/api/work', async (request, reply) =>
-    getWork(request, reply, defaultResourceCode),
+  app.get(
+    '/api/work',
+    async (request, reply): Promise<WorkEnvelope | FastifyReply> => {
+      if (!defaultResourceCode) {
+        return reply.code(400).send({
+          error: 'RESOURCE_CODE_REQUIRED',
+          message:
+            'Provide resourceCode at /api/work/{resourceCode} or configure the optional REALSEE_DEFAULT_RESOURCE_CODE fallback.',
+          requestId: request.id,
+        })
+      }
+      return getWork(request, reply, defaultResourceCode)
+    },
   )
 
   app.get(