@realsee/vr-cli 0.1.5 → 0.2.0

package/templates/base/scripts/pairing.test.mjs

@@ -0,0 +1,227 @@
+import assert from 'node:assert/strict'
+import {
+  chmod,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+import {
+  CONTINUATION_RELATIVE_PATH,
+  readPairingContinuation,
+  runPairingCommand,
+  runPairingCompleteCommand,
+} from './pairing.mjs'
+
+const PORTAL_BASE_URL = 'http://127.0.0.1:43123'
+const APP_KEY = 'test-app-key-1234'
+const APP_SECRET = 'test-app-secret-value'
+const ENV_KEYS = [
+  'REALSEE_PORTAL_BASE_URL',
+  'REALSEE_GATEWAY_APP_KEY',
+  'REALSEE_GATEWAY_APP_SECRET',
+  'REALSEE_DEFAULT_RESOURCE_CODE',
+  'REALSEE_GATEWAY_ENDPOINT',
+]
+
+async function temporaryProject() {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'realsee-pairing-'))
+  await writeFile(
+    path.join(root, 'package.json'),
+    JSON.stringify({ name: 'pairing-test-app' }),
+  )
+  return root
+}
+
+function prepareProcess(t, root) {
+  const previousDirectory = process.cwd()
+  const previousEnv = new Map(ENV_KEYS.map((key) => [key, process.env[key]]))
+  process.chdir(root)
+  for (const key of ENV_KEYS) delete process.env[key]
+  process.env.REALSEE_PORTAL_BASE_URL = PORTAL_BASE_URL
+
+  let stdout = ''
+  let stderr = ''
+  t.mock.method(process.stdout, 'write', (chunk) => {
+    stdout += String(chunk)
+    return true
+  })
+  t.mock.method(process.stderr, 'write', (chunk) => {
+    stderr += String(chunk)
+    return true
+  })
+  t.after(() => {
+    process.chdir(previousDirectory)
+    for (const [key, value] of previousEnv) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+  })
+  return {
+    stdout: () => stdout,
+    stderr: () => stderr,
+    clearOutput: () => {
+      stdout = ''
+      stderr = ''
+    },
+  }
+}
+
+function jsonResponse(value) {
+  return new Response(JSON.stringify(value), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+function installPortalFetch(t) {
+  const observed = { starts: [], polls: 0 }
+  let pollResult = 'denied'
+  t.mock.method(globalThis, 'fetch', async (input, options = {}) => {
+    const url = new URL(input)
+    if (url.pathname === '/api/cli/pairing/start') {
+      observed.starts.push(JSON.parse(options.body))
+      return jsonResponse({
+        ok: true,
+        data: {
+          user_code: 'GPVB-SWBF',
+          verification_uri_complete: `${PORTAL_BASE_URL}/spatial-apps/create/authorize?user_code=GPVB-SWBF`,
+          poll_secret: 'test-poll-secret',
+          interval: 5,
+          expires_in: 300,
+        },
+      })
+    }
+    if (url.pathname === '/api/cli/pairing/poll') {
+      observed.polls += 1
+      assert.equal(options.headers.authorization, 'Bearer test-poll-secret')
+      if (pollResult === 'approved') {
+        return jsonResponse({
+          ok: true,
+          data: {
+            app_key: APP_KEY,
+            app_secret: APP_SECRET,
+            resource_code: 'resource-code-1',
+            gateway_endpoint: 'https://app-gateway.realsee.cn',
+          },
+        })
+      }
+      return jsonResponse({ ok: false, error: { code: 'access_denied' } })
+    }
+    throw new Error(`Unexpected pairing request: ${url.pathname}`)
+  })
+  return {
+    observed,
+    approve: () => {
+      pollResult = 'approved'
+    },
+  }
+}
+
+test('completes the split pairing flow without printing credentials', async (t) => {
+  const root = await temporaryProject()
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const output = prepareProcess(t, root)
+  const portal = installPortalFetch(t)
+
+  const started = await runPairingCommand({ noWait: true, json: true })
+  assert.equal(started, 2)
+  assert.equal(output.stderr(), '')
+  const pending = JSON.parse(output.stdout())
+  assert.equal(pending.ok, true)
+  assert.equal(pending.data.status, 'pending')
+  assert.equal(pending.data.user_code, 'GPVB-SWBF')
+  assert.match(pending.data.client_name, /^pairing-test-app .*#[0-9A-F]{8}$/u)
+  assert.doesNotMatch(output.stdout(), /test-poll-secret|test-app-secret/u)
+  assert.equal(portal.observed.starts.length, 1)
+  assert.equal(portal.observed.starts[0].environment, 'production')
+  assert.deepEqual(portal.observed.starts[0].capabilities, ['poll'])
+
+  const continuation = path.join(root, CONTINUATION_RELATIVE_PATH)
+  assert.equal((await stat(continuation)).mode & 0o777, 0o600)
+  assert.match(await readFile(continuation, 'utf8'), /test-poll-secret/u)
+
+  output.clearOutput()
+  portal.approve()
+  const completed = await runPairingCompleteCommand({ json: true })
+  assert.equal(completed, 0)
+  assert.equal(output.stderr(), '')
+  assert.deepEqual(JSON.parse(output.stdout()), {
+    ok: true,
+    data: {
+      status: 'paired',
+      app_key: 'tes****1234',
+      path: '.env.development',
+    },
+  })
+  assert.doesNotMatch(output.stdout(), /test-poll-secret|test-app-secret/u)
+  assert.equal(portal.observed.polls, 1)
+
+  const localConfig = path.join(root, '.env.development')
+  assert.equal((await stat(localConfig)).mode & 0o777, 0o600)
+  const config = await readFile(localConfig, 'utf8')
+  assert.match(config, /REALSEE_GATEWAY_APP_KEY="test-app-key-1234"/u)
+  assert.match(config, /REALSEE_GATEWAY_APP_SECRET="test-app-secret-value"/u)
+  assert.match(config, /REALSEE_DEFAULT_RESOURCE_CODE="resource-code-1"/u)
+  await assert.rejects(stat(continuation), { code: 'ENOENT' })
+})
+
+test('a denied pairing preserves the existing local configuration', async (t) => {
+  const root = await temporaryProject()
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const output = prepareProcess(t, root)
+  installPortalFetch(t)
+  const localConfig = path.join(root, '.env.development')
+  const existing = 'existing-local-config\n'
+  await writeFile(localConfig, existing)
+  if (process.platform !== 'win32') await chmod(localConfig, 0o600)
+
+  assert.equal(await runPairingCommand({ noWait: true, json: true }), 2)
+  output.clearOutput()
+  assert.equal(await runPairingCompleteCommand({ json: true }), 3)
+  assert.equal(output.stdout(), '')
+  assert.deepEqual(JSON.parse(output.stderr()), {
+    ok: false,
+    error: {
+      code: 'access_denied',
+      message: '用户在 Portal 拒绝了本次配对请求。',
+      hint: '请勿自动重发；请与用户确认原因后重新运行 npm run setup。',
+    },
+  })
+  assert.equal(await readFile(localConfig, 'utf8'), existing)
+  await assert.rejects(stat(path.join(root, CONTINUATION_RELATIVE_PATH)), {
+    code: 'ENOENT',
+  })
+})
+
+test('rejects unsupported continuation schema versions', async () => {
+  const root = await temporaryProject()
+  try {
+    const directory = path.join(root, '.realsee')
+    await mkdir(directory, { mode: 0o700 })
+    await writeFile(
+      path.join(root, CONTINUATION_RELATIVE_PATH),
+      JSON.stringify({
+        schemaVersion: 999,
+        portalBaseUrl: 'https://open.realsee.cn',
+        userCode: 'GPVB-SWBF',
+        verificationUriComplete:
+          'https://open.realsee.cn/spatial-apps/create/authorize?user_code=GPVB-SWBF',
+        pollSecret: 'test-poll-secret',
+        intervalSeconds: 5,
+        expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      }),
+    )
+    await assert.rejects(
+      readPairingContinuation({ root }),
+      /不支持的 schemaVersion/u,
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})

package/templates/base/scripts/project-identity.mjs

@@ -0,0 +1,160 @@
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, open, readFile } from 'node:fs/promises'
+import { hostname, userInfo } from 'node:os'
+import path from 'node:path'
+
+export const PROJECT_IDENTITY_RELATIVE_PATH = '.realsee/project.json'
+// The integrated-commercial-cn pairing create API rejects client_name > 64 chars.
+export const MAX_PAIRING_CLIENT_NAME_LENGTH = 64
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu
+
+function safeString(read) {
+  try {
+    const value = read()
+    return typeof value === 'string' ? value.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+function displayPart(value, fallback) {
+  const cleaned = (typeof value === 'string' ? value : '')
+    .replace(/[\p{Cc}\p{Cf}]/gu, '')
+    .replace(/[·#]/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim()
+  return cleaned || fallback
+}
+
+async function readSavedIdentity(identityPath) {
+  const entry = await lstat(identityPath)
+  if (!entry.isFile() || entry.isSymbolicLink()) {
+    throw new Error(`${PROJECT_IDENTITY_RELATIVE_PATH} 必须是普通文件。`)
+  }
+  let identity
+  try {
+    identity = JSON.parse(await readFile(identityPath, 'utf8'))
+  } catch {
+    throw new Error(
+      `${PROJECT_IDENTITY_RELATIVE_PATH} 内容无效，请检查后再试。`,
+    )
+  }
+  const id = identity?.project_instance_id
+  if (
+    !identity ||
+    typeof identity !== 'object' ||
+    Array.isArray(identity) ||
+    Object.keys(identity).length !== 1 ||
+    typeof id !== 'string' ||
+    !UUID_PATTERN.test(id)
+  ) {
+    throw new Error(`${PROJECT_IDENTITY_RELATIVE_PATH} 缺少有效的项目实例 ID。`)
+  }
+  return id.toLowerCase()
+}
+
+export async function getOrCreateProjectInstanceId(root = process.cwd()) {
+  const projectRoot = path.resolve(root)
+  const directory = path.join(projectRoot, '.realsee')
+  const identityPath = path.join(directory, 'project.json')
+  try {
+    await mkdir(directory, { mode: 0o700 })
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+  }
+  const directoryEntry = await lstat(directory)
+  if (!directoryEntry.isDirectory() || directoryEntry.isSymbolicLink()) {
+    throw new Error('.realsee 必须是当前项目内的普通目录。')
+  }
+
+  const id = randomUUID()
+  let file
+  try {
+    file = await open(identityPath, 'wx', 0o600)
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+    // A concurrent setup may have created the file but not finished writing it.
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+      try {
+        return await readSavedIdentity(identityPath)
+      } catch (readError) {
+        if (attempt === 9 || !String(readError?.message).includes('内容无效')) {
+          throw readError
+        }
+        await new Promise((resolve) => setTimeout(resolve, 20))
+      }
+    }
+  }
+  try {
+    await file.writeFile(
+      `${JSON.stringify({ project_instance_id: id }, null, 2)}\n`,
+      'utf8',
+    )
+    await file.sync()
+  } finally {
+    await file.close()
+  }
+  return id
+}
+
+export async function readProjectName(root = process.cwd()) {
+  const projectRoot = path.resolve(root)
+  try {
+    const manifest = JSON.parse(
+      await readFile(path.join(projectRoot, 'package.json'), 'utf8'),
+    )
+    if (typeof manifest?.name === 'string') {
+      return displayPart(
+        manifest.name,
+        displayPart(path.basename(projectRoot), 'VR App'),
+      )
+    }
+  } catch {
+    // An absent or invalid manifest must not turn a non-sensitive display label
+    // into a blocker for an otherwise valid pairing request.
+  }
+  return displayPart(path.basename(projectRoot), 'VR App')
+}
+
+export function formatPairingClientName({
+  projectName,
+  projectInstanceId,
+  user,
+  machine,
+}) {
+  if (!UUID_PATTERN.test(projectInstanceId)) {
+    throw new Error('项目实例 ID 无效。')
+  }
+  const shortId = projectInstanceId.slice(0, 8).toUpperCase()
+  const suffix = ` · #${shortId}`
+  const available = MAX_PAIRING_CLIENT_NAME_LENGTH - suffix.length
+  const environment = `${displayPart(user, 'unknown')}@${displayPart(machine, 'unknown')}`
+  const limitedEnvironment = environment.slice(0, Math.min(32, available - 5))
+  const projectBudget = available - limitedEnvironment.length - 3
+  const project = displayPart(projectName, 'VR App').slice(0, projectBudget)
+  return `${project} · ${limitedEnvironment}${suffix}`
+}
+
+export async function currentProjectClientName(
+  root = process.cwd(),
+  env = process.env,
+) {
+  const [projectName, projectInstanceId] = await Promise.all([
+    readProjectName(root),
+    getOrCreateProjectInstanceId(root),
+  ])
+  const user =
+    safeString(() => userInfo().username) ||
+    env.USER?.trim() ||
+    env.USERNAME?.trim() ||
+    'unknown'
+  const machine = safeString(hostname) || 'unknown'
+  return formatPairingClientName({
+    projectName,
+    projectInstanceId,
+    user,
+    machine,
+  })
+}

package/templates/base/scripts/project-identity.test.mjs

@@ -0,0 +1,119 @@
+import assert from 'node:assert/strict'
+import {
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import test from 'node:test'
+import {
+  currentProjectClientName,
+  formatPairingClientName,
+  getOrCreateProjectInstanceId,
+  MAX_PAIRING_CLIENT_NAME_LENGTH,
+  readProjectName,
+} from './project-identity.mjs'
+
+async function temporaryProject(name = 'my-vr-app') {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'realsee-project-id-'))
+  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name }))
+  return root
+}
+
+test('keeps one local project ID across repeated pairing attempts', async () => {
+  const root = await temporaryProject()
+  try {
+    const first = await getOrCreateProjectInstanceId(root)
+    const second = await getOrCreateProjectInstanceId(root)
+    assert.equal(second, first)
+    assert.match(first, /^[0-9a-f]{8}-[0-9a-f-]{27}$/u)
+    const identityPath = path.join(root, '.realsee', 'project.json')
+    assert.deepEqual(JSON.parse(await readFile(identityPath, 'utf8')), {
+      project_instance_id: first,
+    })
+    if (process.platform !== 'win32') {
+      assert.equal((await stat(identityPath)).mode & 0o777, 0o600)
+    }
+    assert.match(
+      await currentProjectClientName(root),
+      /my-vr-app.*#[0-9A-F]{8}$/u,
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('distinguishes same-name projects without sharing local configuration', async () => {
+  const firstRoot = await temporaryProject('same-name')
+  const secondRoot = await temporaryProject('same-name')
+  try {
+    const firstId = await getOrCreateProjectInstanceId(firstRoot)
+    const secondId = await getOrCreateProjectInstanceId(secondRoot)
+    assert.notEqual(firstId, secondId)
+    assert.notEqual(
+      formatPairingClientName({
+        projectName: 'same-name',
+        projectInstanceId: firstId,
+        user: 'a',
+        machine: 'm',
+      }),
+      formatPairingClientName({
+        projectName: 'same-name',
+        projectInstanceId: secondId,
+        user: 'a',
+        machine: 'm',
+      }),
+    )
+  } finally {
+    await rm(firstRoot, { recursive: true, force: true })
+    await rm(secondRoot, { recursive: true, force: true })
+  }
+})
+
+test('preserves the short ID while cleaning and bounding the display name', () => {
+  assert.equal(MAX_PAIRING_CLIENT_NAME_LENGTH, 64)
+  const id = '4ec413e0-a832-4c43-8958-7353bdf38df1'
+  const name = formatPairingClientName({
+    projectName: `${'长'.repeat(120)}\n·#`,
+    projectInstanceId: id,
+    user: 'user\u001b',
+    machine: 'machine'.repeat(20),
+  })
+  assert.ok(name.length <= MAX_PAIRING_CLIENT_NAME_LENGTH)
+  assert.match(name, / · #4EC413E0$/u)
+  assert.ok(!name.includes('\r'))
+  assert.ok(!name.includes('\n'))
+  assert.ok(!name.includes('\u001b'))
+})
+
+test('uses only the directory name when package metadata is unavailable', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'realsee-project-id-'))
+  try {
+    assert.equal(await readProjectName(root), path.basename(root))
+    await writeFile(path.join(root, 'package.json'), '{invalid')
+    assert.equal(await readProjectName(root), path.basename(root))
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('rejects invalid or symlinked saved identities instead of replacing them', async () => {
+  const root = await temporaryProject()
+  try {
+    await getOrCreateProjectInstanceId(root)
+    const identityPath = path.join(root, '.realsee', 'project.json')
+    await writeFile(identityPath, '{invalid')
+    await assert.rejects(getOrCreateProjectInstanceId(root), /内容无效/u)
+    if (process.platform !== 'win32') {
+      await rm(identityPath)
+      await symlink(path.join(root, 'package.json'), identityPath)
+      await assert.rejects(getOrCreateProjectInstanceId(root), /普通文件/u)
+    }
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})

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,
+  })
+}