@realsee/vr-cli 0.1.5 → 0.2.0

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(