@realsee/vr-cli 0.1.5 → 0.2.0

package/templates/base/scripts/pairing.mjs

@@ -0,0 +1,564 @@
+import { lstat, readFile, rm } from 'node:fs/promises'
+import path from 'node:path'
+import { currentProjectClientName } from './project-identity.mjs'
+import {
+  normalizeGatewayCredentials,
+  writeLocalConfig,
+  writePrivateFile,
+} from './setup-config.mjs'
+
+// First-phase pairing runs against the anonymous Portal endpoints only. The
+// base URL is overridable for staging/lan testing; protocol paths never change.
+export const DEFAULT_PORTAL_BASE_URL = 'https://open.realsee.cn'
+export const PORTAL_BASE_URL_ENV_KEY = 'REALSEE_PORTAL_BASE_URL'
+export const CONTINUATION_RELATIVE_PATH = '.realsee/pairing-continuation.json'
+export const CONTINUATION_SCHEMA_VERSION = 1
+export const NEXT_STEP_COMMAND = 'npm run setup -- --complete'
+export const CLIENT_VERSION = 'vr-cli/{{TOOL_VERSION}}'
+// The pairing start request carries the documented environment/capabilities
+// fields; `production` is the only value the protocol defines today.
+export const PAIRING_ENVIRONMENT = 'production'
+
+export const PAIRING_EXIT_CODES = Object.freeze({
+  OK: 0,
+  ERROR: 1,
+  PENDING: 2,
+  DENIED: 3,
+  EXPIRED: 4,
+  UNAVAILABLE: 5,
+})
+
+const MIN_INTERVAL_SECONDS = 5
+const MAX_INTERVAL_SECONDS = 60
+const SLOW_DOWN_STEP_SECONDS = 5
+const MIN_WINDOW_SECONDS = 60
+const MAX_WINDOW_SECONDS = 3_600
+const REQUEST_TIMEOUT_MS = 30_000
+
+const START_PATH = '/api/cli/pairing/start'
+const POLL_PATH = '/api/cli/pairing/poll'
+
+export class PairingError extends Error {
+  constructor({ code, message, hint, exitCode = PAIRING_EXIT_CODES.ERROR }) {
+    super(message)
+    this.name = 'PairingError'
+    this.code = code
+    this.hint = hint
+    this.exitCode = exitCode
+  }
+}
+
+function configurationError(message, hint) {
+  return new PairingError({
+    code: 'configuration_invalid',
+    message,
+    hint,
+  })
+}
+
+function unavailableError(message, hint) {
+  return new PairingError({
+    code: 'server_unavailable',
+    message,
+    hint,
+    exitCode: PAIRING_EXIT_CODES.UNAVAILABLE,
+  })
+}
+
+function interruptedError(message, hint) {
+  return new PairingError({
+    code: 'network_unavailable',
+    message,
+    hint,
+    exitCode: PAIRING_EXIT_CODES.UNAVAILABLE,
+  })
+}
+
+function clampIntervalSeconds(value) {
+  const seconds = Number(value)
+  if (!Number.isFinite(seconds)) return MIN_INTERVAL_SECONDS
+  return Math.min(
+    MAX_INTERVAL_SECONDS,
+    Math.max(MIN_INTERVAL_SECONDS, Math.floor(seconds)),
+  )
+}
+
+function clampWindowSeconds(value) {
+  const seconds = Number(value)
+  if (!Number.isFinite(seconds)) return MAX_WINDOW_SECONDS
+  return Math.min(
+    MAX_WINDOW_SECONDS,
+    Math.max(MIN_WINDOW_SECONDS, Math.floor(seconds)),
+  )
+}
+
+function isLoopbackHost(host) {
+  return (
+    host === 'localhost' ||
+    host === '127.0.0.1' ||
+    host === '[::1]' ||
+    host === '::1'
+  )
+}
+
+export function resolvePortalBaseUrl(env = process.env) {
+  const raw = env[PORTAL_BASE_URL_ENV_KEY]?.trim()
+  if (!raw) return DEFAULT_PORTAL_BASE_URL
+  let url
+  try {
+    url = new URL(raw)
+  } catch {
+    throw configurationError(
+      `${PORTAL_BASE_URL_ENV_KEY} 不是合法 URL：${raw}`,
+      `请修正或删除 ${PORTAL_BASE_URL_ENV_KEY} 后重试。`,
+    )
+  }
+  const loopback = isLoopbackHost(url.hostname)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+    throw configurationError(
+      `${PORTAL_BASE_URL_ENV_KEY} 必须使用 HTTPS（本机回环地址除外）：${raw}`,
+      `请修正或删除 ${PORTAL_BASE_URL_ENV_KEY} 后重试。`,
+    )
+  }
+  const basePath = url.pathname.replace(/\/+$/u, '')
+  return `${url.origin}${basePath}`
+}
+
+function parseJson(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+async function requestJson(url, options = {}) {
+  let response
+  try {
+    response = await fetch(url, {
+      ...options,
+      headers: { accept: 'application/json', ...(options.headers ?? {}) },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    })
+  } catch (error) {
+    throw interruptedError(
+      `无法连接配对服务：${error instanceof Error ? error.message : '网络错误'}`,
+      '请确认网络与 Portal 可用后重新运行 npm run setup。',
+    )
+  }
+
+  const payload = parseJson(await response.text().catch(() => ''))
+  if (
+    payload === null ||
+    typeof payload !== 'object' ||
+    Array.isArray(payload)
+  ) {
+    throw unavailableError(
+      `配对服务返回了无法解析的响应（HTTP ${response.status}）。`,
+      '请稍后重试；若持续出现请联系 Portal 维护者。',
+    )
+  }
+  if (payload.ok === true && !response.ok) {
+    throw unavailableError(
+      `配对服务返回 HTTP ${response.status}。`,
+      '请稍后重试；若持续出现请联系 Portal 维护者。',
+    )
+  }
+  return payload
+}
+
+function requireString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw unavailableError(
+      `配对服务响应缺少 ${label}。`,
+      '请稍后重试；若持续出现请联系 Portal 维护者。',
+    )
+  }
+  return value
+}
+
+function optionalString(value) {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
+async function startPairingSession({ baseUrl, clientName, clientVersion }) {
+  const payload = await requestJson(`${baseUrl}${START_PATH}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      client_name: clientName,
+      client_version: clientVersion,
+      environment: PAIRING_ENVIRONMENT,
+      capabilities: ['poll'],
+    }),
+  })
+  if (payload.ok !== true) {
+    const code = payload.error?.code ?? 'unknown_error'
+    throw unavailableError(
+      `配对服务拒绝了发起请求（${code}）。`,
+      '请稍后重试；若持续出现请联系 Portal 维护者。',
+    )
+  }
+  const data = payload.data
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    throw unavailableError(
+      '配对服务响应缺少 data。',
+      '请稍后重试；若持续出现请联系 Portal 维护者。',
+    )
+  }
+  return {
+    userCode: requireString(data.user_code, 'user_code'),
+    verificationUriComplete: requireString(
+      data.verification_uri_complete,
+      'verification_uri_complete',
+    ),
+    pollSecret: requireString(data.poll_secret, 'poll_secret'),
+    intervalSeconds: clampIntervalSeconds(data.interval),
+    expiresAtMs: Date.now() + clampWindowSeconds(data.expires_in) * 1_000,
+  }
+}
+
+async function pollPairingRequest({ baseUrl, pollSecret }) {
+  return requestJson(`${baseUrl}${POLL_PATH}`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${pollSecret}`,
+      'content-type': 'application/json',
+    },
+    body: '{}',
+  })
+}
+
+function sleepFor(milliseconds) {
+  if (milliseconds <= 0) return Promise.resolve()
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+async function waitForPairingResult({ baseUrl, session }) {
+  let intervalSeconds = session.intervalSeconds
+
+  for (;;) {
+    if (Date.now() >= session.expiresAtMs) return { status: 'expired' }
+
+    const payload = await pollPairingRequest({
+      baseUrl,
+      pollSecret: session.pollSecret,
+    })
+    if (payload.ok === true) {
+      const data = payload.data
+      if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+        throw unavailableError(
+          '配对服务响应缺少 data。',
+          '请稍后重试；若持续出现请联系 Portal 维护者。',
+        )
+      }
+      return {
+        status: 'approved',
+        credentials: {
+          appKey: requireString(data.app_key, 'app_key'),
+          appSecret: requireString(data.app_secret, 'app_secret'),
+          resourceCode: optionalString(data.resource_code),
+          gatewayEndpoint: optionalString(data.gateway_endpoint),
+        },
+      }
+    }
+
+    const code = payload.error?.code
+    if (code === 'authorization_pending') {
+      await sleepFor(
+        Math.min(intervalSeconds * 1_000, session.expiresAtMs - Date.now()),
+      )
+      continue
+    }
+    if (code === 'slow_down') {
+      intervalSeconds = clampIntervalSeconds(
+        intervalSeconds + SLOW_DOWN_STEP_SECONDS,
+      )
+      await sleepFor(
+        Math.min(intervalSeconds * 1_000, session.expiresAtMs - Date.now()),
+      )
+      continue
+    }
+    if (code === 'access_denied') return { status: 'denied' }
+    if (code === 'expired_token') return { status: 'expired' }
+    throw unavailableError(
+      `配对服务返回了未知状态：${code ?? '未知'}。`,
+      '请稍后重试；若持续出现请联系 Portal 维护者。',
+    )
+  }
+}
+
+export function maskAppKey(appKey) {
+  if (typeof appKey !== 'string' || appKey.length < 12) return '****'
+  return `${appKey.slice(0, 3)}****${appKey.slice(-4)}`
+}
+
+function formatTimestamp(milliseconds) {
+  return new Date(milliseconds).toISOString().replace(/\.\d{3}Z$/u, 'Z')
+}
+
+function successEnvelope(data) {
+  return { ok: true, data }
+}
+
+function failureEnvelope(error) {
+  return {
+    ok: false,
+    error: {
+      code: error.code,
+      message: error.message,
+      ...(error.hint ? { hint: error.hint } : {}),
+    },
+  }
+}
+
+function writeJsonLine(stream, value) {
+  stream.write(`${JSON.stringify(value)}\n`)
+}
+
+function writeHumanLines(enabled, lines) {
+  if (!enabled) return
+  for (const line of lines) process.stderr.write(`${line}\n`)
+}
+
+export function continuationPath(root = process.cwd()) {
+  return path.join(path.resolve(root), ...CONTINUATION_RELATIVE_PATH.split('/'))
+}
+
+async function hasLocalConfig(root = process.cwd()) {
+  try {
+    await lstat(path.join(path.resolve(root), '.env.development'))
+    return true
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+export async function writePairingContinuation({
+  root = process.cwd(),
+  baseUrl,
+  session,
+  ...writeOptions
+}) {
+  const content = `${JSON.stringify(
+    {
+      schemaVersion: CONTINUATION_SCHEMA_VERSION,
+      portalBaseUrl: baseUrl,
+      userCode: session.userCode,
+      verificationUriComplete: session.verificationUriComplete,
+      pollSecret: session.pollSecret,
+      intervalSeconds: session.intervalSeconds,
+      expiresAt: new Date(session.expiresAtMs).toISOString(),
+      createdAt: new Date().toISOString(),
+    },
+    null,
+    2,
+  )}\n`
+  return writePrivateFile(continuationPath(root), content, writeOptions)
+}
+
+function continuationInvalid(message) {
+  return new PairingError({
+    code: 'continuation_invalid',
+    message: `配对续跑文件 ${CONTINUATION_RELATIVE_PATH} ${message}`,
+    hint: '请删除该文件后重新运行 npm run setup。',
+  })
+}
+
+function continuationString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw continuationInvalid(`缺少有效的 ${label}。`)
+  }
+  return value
+}
+
+export async function readPairingContinuation({ root = process.cwd() } = {}) {
+  let text
+  try {
+    text = await readFile(continuationPath(root), 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new PairingError({
+        code: 'continuation_missing',
+        message: `未找到配对续跑文件 ${CONTINUATION_RELATIVE_PATH}。`,
+        hint: '请先运行 npm run setup -- --no-wait --json 或 npm run setup。',
+      })
+    }
+    throw error
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    parsed = null
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw continuationInvalid('已损坏。')
+  }
+  if (parsed.schemaVersion !== CONTINUATION_SCHEMA_VERSION) {
+    throw continuationInvalid('使用了不支持的 schemaVersion。')
+  }
+  const expiresAtMs = Date.parse(parsed.expiresAt)
+  if (Number.isNaN(expiresAtMs)) {
+    throw continuationInvalid('缺少有效的 expiresAt。')
+  }
+  return {
+    baseUrl: resolvePortalBaseUrl({
+      [PORTAL_BASE_URL_ENV_KEY]: continuationString(
+        parsed.portalBaseUrl,
+        'portalBaseUrl',
+      ),
+    }),
+    session: {
+      userCode: continuationString(parsed.userCode, 'userCode'),
+      verificationUriComplete: continuationString(
+        parsed.verificationUriComplete,
+        'verificationUriComplete',
+      ),
+      pollSecret: continuationString(parsed.pollSecret, 'pollSecret'),
+      intervalSeconds: clampIntervalSeconds(parsed.intervalSeconds),
+      expiresAtMs,
+    },
+  }
+}
+
+export async function clearPairingContinuation({ root = process.cwd() } = {}) {
+  await rm(continuationPath(root), { force: true })
+}
+
+async function persistCredentials(credentials) {
+  const config = normalizeGatewayCredentials({
+    appKey: credentials.appKey,
+    appSecret: credentials.appSecret,
+    ...(credentials.resourceCode === undefined
+      ? {}
+      : { resourceCode: credentials.resourceCode }),
+    ...(credentials.gatewayEndpoint === undefined
+      ? {}
+      : { gatewayEndpoint: credentials.gatewayEndpoint }),
+  })
+  try {
+    await writeLocalConfig(config)
+  } catch (error) {
+    throw new PairingError({
+      code: 'write_failed',
+      message: `写入 .env.development 失败：${
+        error instanceof Error ? error.message : '未知错误'
+      }`,
+      hint: '请检查当前目录权限后重新运行 npm run setup。',
+    })
+  }
+  return config
+}
+
+async function finishPairingResult(result, { json }) {
+  if (result.status === 'approved') {
+    const config = await persistCredentials(result.credentials)
+    await clearPairingContinuation()
+    writeHumanLines(json !== true, [
+      `配对完成，已原子写入 .env.development（AK ${maskAppKey(config.appKey)}）。请回到 AI 助手并回复“已完成”。`,
+    ])
+    writeJsonLine(
+      process.stdout,
+      successEnvelope({
+        status: 'paired',
+        app_key: maskAppKey(config.appKey),
+        path: '.env.development',
+      }),
+    )
+    return PAIRING_EXIT_CODES.OK
+  }
+
+  await clearPairingContinuation()
+  if (result.status === 'denied') {
+    throw new PairingError({
+      code: 'access_denied',
+      message: '用户在 Portal 拒绝了本次配对请求。',
+      hint: '请勿自动重发；请与用户确认原因后重新运行 npm run setup。',
+      exitCode: PAIRING_EXIT_CODES.DENIED,
+    })
+  }
+  throw new PairingError({
+    code: 'expired_token',
+    message: '配对请求已过期。',
+    hint: '请重新运行 npm run setup 发起新的配对请求。',
+    exitCode: PAIRING_EXIT_CODES.EXPIRED,
+  })
+}
+
+export function reportPairingFailure(error, { json = false } = {}) {
+  const pairingError =
+    error instanceof PairingError
+      ? error
+      : new PairingError({
+          code: 'unexpected_error',
+          message: error instanceof Error ? error.message : '未知错误。',
+          hint: '请重新运行 npm run setup，或改用 npm run setup -- --paste。',
+        })
+  writeHumanLines(json !== true, [`配对失败：${pairingError.message}`])
+  writeJsonLine(process.stderr, failureEnvelope(pairingError))
+  return pairingError.exitCode
+}
+
+export async function runPairingCommand({ noWait = false, json = false } = {}) {
+  try {
+    const baseUrl = resolvePortalBaseUrl()
+    const clientName = await currentProjectClientName()
+    const replacingConfig = await hasLocalConfig()
+    const session = await startPairingSession({
+      baseUrl,
+      clientName,
+      clientVersion: CLIENT_VERSION,
+    })
+    await writePairingContinuation({ baseUrl, session })
+    const expiresAt = formatTimestamp(session.expiresAtMs)
+
+    const closingLine = noWait
+      ? `用户确认后运行：${NEXT_STEP_COMMAND}`
+      : '等待用户在 Portal 确认…'
+    writeHumanLines(json !== true, [
+      `已发起配对请求，有效期至 ${expiresAt}。`,
+      `项目与发起环境：${clientName}`,
+      ...(replacingConfig
+        ? ['确认成功后仅替换当前项目的本地配置，其他项目不受影响。']
+        : []),
+      '请在浏览器中打开并确认（不要把该链接转发给他人）：',
+      session.verificationUriComplete,
+      `核对短码：${session.userCode}`,
+      closingLine,
+    ])
+
+    if (noWait) {
+      writeJsonLine(
+        process.stdout,
+        successEnvelope({
+          status: 'pending',
+          client_name: clientName,
+          replacing_config: replacingConfig,
+          user_code: session.userCode,
+          verification_uri_complete: session.verificationUriComplete,
+          expires_at: expiresAt,
+          next_step: NEXT_STEP_COMMAND,
+        }),
+      )
+      return PAIRING_EXIT_CODES.PENDING
+    }
+
+    const result = await waitForPairingResult({ baseUrl, session })
+    return await finishPairingResult(result, { json })
+  } catch (error) {
+    return reportPairingFailure(error, { json })
+  }
+}
+
+export async function runPairingCompleteCommand({ json = false } = {}) {
+  try {
+    const { baseUrl, session } = await readPairingContinuation()
+    const result = await waitForPairingResult({ baseUrl, session })
+    return await finishPairingResult(result, { json })
+  } catch (error) {
+    return reportPairingFailure(error, { json })
+  }
+}