@unibridge/sdk 0.5.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@unibridge/sdk",
+  "version": "0.5.0",
+  "description": "",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "node --test src/*.test.ts src/**/*.test.ts",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "valibot": "^1.2.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto'
+import { PipeConnection } from './connection.ts'
+import { pipePath } from './hash.ts'
+import { findUnityProject } from './project.ts'
+import type { ClientOptions, CommandResponse, UniBridgeClient } from './types.ts'
+import { buildClientMethods } from './commands/define.ts'
+import type { CommandRuntime, ExecuteGuard } from './commands/runtime.ts'
+import { allCommands } from './commands/registry.ts'
+
+export class UniBridgeError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UniBridgeError'
+  }
+}
+
+function unwrap(response: CommandResponse): unknown {
+  if (!response.success) {
+    throw new UniBridgeError(response.error ?? 'Command failed')
+  }
+  return response.result
+}
+
+function createRuntime(
+  sendCommand: (command: string, params: Record<string, unknown>) => Promise<CommandResponse>,
+  ensureExecuteEnabled: () => void,
+): CommandRuntime & ExecuteGuard {
+  return {
+    async send(command: string, params: Record<string, unknown>): Promise<unknown> {
+      return unwrap(await sendCommand(command, params))
+    },
+    ensureExecuteEnabled,
+  }
+}
+
+export function createClient(options: ClientOptions = {}): UniBridgeClient {
+  const projectPath = options.projectPath ?? findUnityProject()
+  const connection = new PipeConnection({
+    projectPath,
+    connectTimeout: options.connectTimeout,
+    commandTimeout: options.commandTimeout,
+    reconnectTimeout: options.reconnectTimeout,
+  })
+  const callerExecuteEnabled = options.enableExecute ?? true
+
+  async function sendCommand(
+    command: string,
+    params: Record<string, unknown>,
+  ): Promise<CommandResponse> {
+    await connection.connect(pipePath(projectPath))
+    return connection.send({ id: randomUUID(), command, params })
+  }
+
+  function ensureExecuteEnabled(): void {
+    if (!callerExecuteEnabled) {
+      throw new UniBridgeError('Execute is disabled by client or plugin configuration.')
+    }
+
+    const metadata = connection.serverMetadata()
+    const serverExecuteEnabled = metadata?.capabilities?.executeEnabled ?? true
+    if (!serverExecuteEnabled) {
+      throw new UniBridgeError('Execute is disabled by client or plugin configuration.')
+    }
+  }
+
+  const runtime = createRuntime(sendCommand, ensureExecuteEnabled)
+
+  return {
+    projectPath,
+    ...buildClientMethods(runtime, allCommands),
+    close(): void {
+      connection.disconnect()
+    },
+  }
+}
+

package/src/commands/contracts.ts

@@ -0,0 +1,4 @@
+export type { DomainReloadResult } from './domain/contract.ts'
+export type { ExecuteResult } from './execute/contract.ts'
+export type { SceneActiveResult, SceneCreateResult, SceneInfo, SceneOpenResult } from './scene/contract.ts'
+export type { StatusResult } from './status/contract.ts'

package/src/commands/define.ts

@@ -0,0 +1,56 @@
+import * as v from 'valibot'
+import type { CommandRuntime, ExecuteGuard } from './runtime.ts'
+
+export interface CommandDef<
+  TMethod extends string,
+  TArgs extends unknown[],
+  TResult,
+> {
+  readonly method: TMethod
+  readonly wire: string
+  readonly params: (...args: TArgs) => Record<string, unknown>
+  readonly result: v.GenericSchema<unknown, TResult>
+  readonly guard?: 'execute'
+}
+
+export function defineCommand<
+  TMethod extends string,
+  TArgs extends unknown[],
+  TResult,
+>(def: CommandDef<TMethod, TArgs, TResult>): CommandDef<TMethod, TArgs, TResult> {
+  return def
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type InferResult<T> = T extends CommandDef<string, any[], infer R> ? R : never
+
+type CommandMethod<T> = T extends CommandDef<string, infer TArgs, infer TResult>
+  ? (...args: TArgs) => Promise<TResult>
+  : never
+
+export type CommandMethods<T extends readonly CommandDef<string, any[], any>[]> = {
+  [K in T[number] as K['method']]: CommandMethod<K>
+}
+
+export async function invokeCommand<TArgs extends unknown[], TResult>(
+  def: CommandDef<string, TArgs, TResult>,
+  runtime: CommandRuntime & ExecuteGuard,
+  ...args: TArgs
+): Promise<TResult> {
+  if (def.guard === 'execute') {
+    runtime.ensureExecuteEnabled()
+  }
+  const params = def.params(...args)
+  const raw = await runtime.send(def.wire, params)
+  return v.parse(def.result, raw)
+}
+
+export function buildClientMethods<
+  const T extends readonly CommandDef<string, any[], any>[],
+>(runtime: CommandRuntime & ExecuteGuard, defs: T): CommandMethods<T> {
+  const methods: Record<string, (...args: unknown[]) => Promise<unknown>> = {}
+  for (const def of defs) {
+    methods[def.method] = (...args: unknown[]) => invokeCommand(def, runtime, ...args)
+  }
+  return methods as CommandMethods<T>
+}

package/src/commands/domain/contract.ts

@@ -0,0 +1,15 @@
+import * as v from 'valibot'
+import { defineCommand, type InferResult } from '../define.ts'
+
+export const DomainReloadResultSchema = v.object({
+  triggered: v.boolean(),
+})
+
+export const domainReloadCommand = defineCommand({
+  method: 'domainReload',
+  wire: 'domain.reload',
+  params: () => ({}),
+  result: DomainReloadResultSchema,
+})
+
+export type DomainReloadResult = InferResult<typeof domainReloadCommand>

package/src/commands/execute/contract.ts

@@ -0,0 +1,12 @@
+import * as v from 'valibot'
+import { defineCommand, type InferResult } from '../define.ts'
+
+export const executeCommand = defineCommand({
+  method: 'execute',
+  wire: 'execute',
+  params: (code: string) => ({ code }),
+  result: v.unknown(),
+  guard: 'execute',
+})
+
+export type ExecuteResult = InferResult<typeof executeCommand>

package/src/commands/registry.ts

@@ -0,0 +1,6 @@
+import { domainReloadCommand } from './domain/contract.ts'
+import { executeCommand } from './execute/contract.ts'
+import { sceneActiveCommand, sceneCreateCommand, sceneOpenCommand } from './scene/contract.ts'
+import { statusCommand } from './status/contract.ts'
+
+export const allCommands = [domainReloadCommand, executeCommand, statusCommand, sceneActiveCommand, sceneCreateCommand, sceneOpenCommand] as const

package/src/commands/runtime.ts

@@ -0,0 +1,7 @@
+export interface CommandRuntime {
+  send(command: string, params: Record<string, unknown>): Promise<unknown>
+}
+
+export interface ExecuteGuard {
+  ensureExecuteEnabled(): void
+}

package/src/commands/scene/contract.ts

@@ -0,0 +1,46 @@
+import * as v from 'valibot'
+import { defineCommand, type InferResult } from '../define.ts'
+
+const SceneInfoSchema = v.object({
+  name: v.string(),
+  path: v.string(),
+  isDirty: v.boolean(),
+})
+
+export const SceneActiveResultSchema = v.object({
+  scene: SceneInfoSchema,
+})
+
+export const sceneActiveCommand = defineCommand({
+  method: 'sceneActive',
+  wire: 'scene.active',
+  params: () => ({}),
+  result: SceneActiveResultSchema,
+})
+
+export const SceneOpenResultSchema = v.object({
+  scene: SceneInfoSchema,
+})
+
+export const sceneOpenCommand = defineCommand({
+  method: 'sceneOpen',
+  wire: 'scene.open',
+  params: (path: string) => ({ path }),
+  result: SceneOpenResultSchema,
+})
+
+export const SceneCreateResultSchema = v.object({
+  scene: SceneInfoSchema,
+})
+
+export const sceneCreateCommand = defineCommand({
+  method: 'sceneCreate',
+  wire: 'scene.create',
+  params: (path: string) => ({ path }),
+  result: SceneCreateResultSchema,
+})
+
+export type SceneInfo = v.InferOutput<typeof SceneInfoSchema>
+export type SceneActiveResult = InferResult<typeof sceneActiveCommand>
+export type SceneOpenResult = InferResult<typeof sceneOpenCommand>
+export type SceneCreateResult = InferResult<typeof sceneCreateCommand>

package/src/commands/status/contract.ts

@@ -0,0 +1,19 @@
+import * as v from 'valibot'
+import { defineCommand, type InferResult } from '../define.ts'
+
+export const StatusResultSchema = v.object({
+  projectPath: v.string(),
+  unityVersion: v.string(),
+  pluginVersion: v.string(),
+  activeScene: v.string(),
+  playMode: v.string(),
+})
+
+export const statusCommand = defineCommand({
+  method: 'status',
+  wire: 'status',
+  params: () => ({}),
+  result: StatusResultSchema,
+})
+
+export type StatusResult = InferResult<typeof statusCommand>

package/src/connection.test.ts

@@ -0,0 +1,330 @@
+import { afterEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import net from 'node:net'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { PipeConnection } from './connection.ts'
+import { stateDir } from './hash.ts'
+
+const SOCK_PATH = '/tmp/unibridge-test.sock'
+
+function createMockServer(handler: (data: Buffer) => Buffer) {
+  const sockets = new Set<net.Socket>()
+  const server = net.createServer((socket) => {
+    sockets.add(socket)
+    socket.on('close', () => {
+      sockets.delete(socket)
+    })
+    let buffer = Buffer.alloc(0)
+    socket.on('data', (chunk: Buffer | string) => {
+      const data = typeof chunk === 'string' ? Buffer.from(chunk) : chunk
+      buffer = Buffer.concat([buffer, data])
+      while (buffer.length >= 4) {
+        const len = buffer.readUInt32BE(0)
+        if (buffer.length < 4 + len) break
+        const msg = buffer.subarray(4, 4 + len)
+        buffer = buffer.subarray(4 + len)
+        const response = handler(msg)
+        const frame = Buffer.alloc(4 + response.length)
+        frame.writeUInt32BE(response.length, 0)
+        response.copy(frame, 4)
+        socket.write(frame)
+      }
+    })
+  })
+
+  try {
+    fs.unlinkSync(SOCK_PATH)
+  } catch {
+    // ignore missing socket
+  }
+
+  server.listen(SOCK_PATH)
+  const closeWithClients = server.close.bind(server)
+    ; (server as net.Server & { close: net.Server['close'] }).close = ((callback?: (err?: Error) => void) => {
+      for (const socket of sockets) {
+        socket.destroy()
+      }
+      sockets.clear()
+      return closeWithClients(callback)
+    }) as net.Server['close']
+  return server
+}
+
+describe('PipeConnection', () => {
+  let server: net.Server | undefined
+  let conn: PipeConnection | undefined
+  let projectPath: string | undefined
+
+  afterEach(async () => {
+    conn?.disconnect()
+    if (server) {
+      await new Promise<void>((resolve) => server?.close(() => resolve()))
+    }
+    try {
+      fs.unlinkSync(SOCK_PATH)
+    } catch {
+      // ignore missing socket
+    }
+    if (projectPath) {
+      fs.rmSync(projectPath, { recursive: true, force: true })
+      projectPath = undefined
+    }
+  })
+
+  it('connects and sends/receives a message', async () => {
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      return Buffer.from(JSON.stringify({
+        id: req.id,
+        success: true,
+        result: 'hello',
+      }))
+    })
+
+    conn = new PipeConnection()
+    await conn.connect(SOCK_PATH)
+    const res = await conn.send({
+      id: 'cmd-1',
+      command: 'execute',
+      params: { code: 'test' },
+    })
+
+    assert.equal(res.success, true)
+    assert.equal(res.result, 'hello')
+  })
+
+  it('deletes persisted result file after socket response is processed', async () => {
+    projectPath = fs.mkdtempSync(path.join(os.tmpdir(), 'unibridge-project-'))
+    const stateDirectory = stateDir(projectPath)
+    fs.mkdirSync(path.join(stateDirectory, 'results'), { recursive: true })
+
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      const resultPath = path.join(stateDirectory, 'results', `${req.id}.json`)
+      fs.writeFileSync(resultPath, JSON.stringify({
+        id: req.id,
+        success: true,
+        result: 'socket-path',
+        error: null,
+      }))
+
+      return Buffer.from(JSON.stringify({
+        id: req.id,
+        success: true,
+        result: 'socket-path',
+      }))
+    })
+
+    conn = new PipeConnection({ projectPath })
+    await conn.connect(SOCK_PATH)
+    const response = await conn.send({
+      id: 'cmd-socket-cleanup',
+      command: 'execute',
+      params: { code: 'Debug.Log("x")' },
+    })
+
+    assert.equal(response.success, true)
+    assert.equal(response.result, 'socket-path')
+    const resultPath = path.join(stateDirectory, 'results', 'cmd-socket-cleanup.json')
+    assert.equal(fs.existsSync(resultPath), false)
+  })
+
+  it('matches responses to requests by ID', async () => {
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      return Buffer.from(JSON.stringify({
+        id: req.id,
+        success: true,
+        result: req.id,
+      }))
+    })
+
+    conn = new PipeConnection()
+    await conn.connect(SOCK_PATH)
+    const [a, b] = await Promise.all([
+      conn.send({ id: 'cmd-a', command: 'execute', params: {} }),
+      conn.send({ id: 'cmd-b', command: 'execute', params: {} }),
+    ])
+
+    assert.equal(a.result, 'cmd-a')
+    assert.equal(b.result, 'cmd-b')
+  })
+
+  it('reconnects after server restarts', async () => {
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      return Buffer.from(JSON.stringify({ id: req.id, success: true, result: 'ok' }))
+    })
+
+    conn = new PipeConnection({ reconnectTimeout: 5000 })
+    await conn.connect(SOCK_PATH)
+
+    await new Promise<void>((resolve) => server?.close(() => resolve()))
+    try {
+      fs.unlinkSync(SOCK_PATH)
+    } catch {
+      // ignore missing socket
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 300))
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      return Buffer.from(JSON.stringify({
+        id: req.id,
+        success: true,
+        result: 'reconnected',
+      }))
+    })
+
+    const res = await conn.send({
+      id: 'cmd-2',
+      command: 'execute',
+      params: {},
+    })
+
+    assert.equal(res.result, 'reconnected')
+  })
+
+  it('recovers pending response after reconnect without re-sending execute', async () => {
+    projectPath = fs.mkdtempSync(path.join(os.tmpdir(), 'unibridge-project-'))
+    const stateDirectory = stateDir(projectPath)
+    fs.mkdirSync(path.join(stateDirectory, 'results'), { recursive: true })
+
+    let sawExecute = false
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      if (req.command === 'execute') {
+        sawExecute = true
+        setTimeout(() => {
+          server?.close()
+          try {
+            fs.unlinkSync(SOCK_PATH)
+          } catch {
+            // ignore missing socket
+          }
+          server = createMockServer((nextMsg) => {
+            const recoverReq = JSON.parse(nextMsg.toString())
+            if (recoverReq.command === 'recoverResults') {
+              const resultPath = path.join(stateDirectory, 'results', 'cmd-recover.json')
+              fs.writeFileSync(resultPath, JSON.stringify({
+                id: 'cmd-recover',
+                success: true,
+                result: 'recovered',
+                error: null,
+              }))
+              return Buffer.from(JSON.stringify({
+                id: recoverReq.id,
+                success: true,
+                result: JSON.stringify({
+                  results: [
+                    {
+                      id: 'cmd-recover',
+                      success: true,
+                      result: 'recovered',
+                      error: null,
+                    },
+                  ],
+                }),
+              }))
+            }
+            return Buffer.from(JSON.stringify({
+              id: recoverReq.id,
+              success: false,
+              error: 'unexpected command',
+            }))
+          })
+        }, 50)
+        return Buffer.alloc(0)
+      }
+
+      return Buffer.from(JSON.stringify({
+        id: req.id,
+        success: false,
+        error: 'unexpected command',
+      }))
+    })
+
+    conn = new PipeConnection({ projectPath, commandTimeout: 2000, reconnectTimeout: 5000 })
+    await conn.connect(SOCK_PATH)
+    const response = await conn.send({
+      id: 'cmd-recover',
+      command: 'execute',
+      params: { code: 'Debug.Log("x")' },
+    })
+
+    assert.equal(sawExecute, true)
+    assert.equal(response.success, true)
+    assert.equal(response.result, 'recovered')
+    const recoveredResultPath = path.join(stateDirectory, 'results', 'cmd-recover.json')
+    assert.equal(fs.existsSync(recoveredResultPath), false)
+  })
+
+  it('does NOT re-send commands on reconnect', async () => {
+    let commandCount = 0
+    server = createMockServer(() => {
+      commandCount++
+      return Buffer.alloc(0)
+    })
+
+    conn = new PipeConnection({ commandTimeout: 500, reconnectTimeout: 2000 })
+    await conn.connect(SOCK_PATH)
+
+    const promise = conn.send({
+      id: 'cmd-reload',
+      command: 'execute',
+      params: {},
+    })
+
+    await assert.rejects(promise, /timeout/i)
+    assert.equal(commandCount, 1)
+  })
+
+  it('fires connect timeout when no server', async () => {
+    conn = new PipeConnection({ connectTimeout: 500 })
+    await assert.rejects(conn.connect('/tmp/nonexistent.sock'), /Connect timeout/i)
+  })
+
+  it('returns file result when socket response is lost during reload window', async () => {
+    projectPath = fs.mkdtempSync(path.join(os.tmpdir(), 'unibridge-project-'))
+    const stateDirectory = stateDir(projectPath)
+    fs.mkdirSync(path.join(stateDirectory, 'results'), { recursive: true })
+
+    server = createMockServer((msg) => {
+      const req = JSON.parse(msg.toString())
+      if (req.command === 'execute') {
+        setTimeout(() => {
+          const resultPath = path.join(stateDirectory, 'results', `${req.id}.json`)
+          fs.writeFileSync(resultPath, JSON.stringify({
+            id: req.id,
+            success: true,
+            result: 'from-file',
+            error: null,
+          }))
+        }, 100)
+        return Buffer.alloc(0)
+      }
+
+      return Buffer.from(JSON.stringify({
+        id: req.id,
+        success: false,
+        error: 'unexpected command',
+      }))
+    })
+
+    conn = new PipeConnection({ projectPath, commandTimeout: 1000, reconnectTimeout: 1000 })
+    await conn.connect(SOCK_PATH)
+
+    const response = await conn.send({
+      id: 'cmd-file-fallback',
+      command: 'execute',
+      params: { code: 'Debug.Log("x")' },
+    })
+
+    assert.equal(response.success, true)
+    assert.equal(response.result, 'from-file')
+    const resultPath = path.join(stateDirectory, 'results', 'cmd-file-fallback.json')
+    assert.equal(fs.existsSync(resultPath), false)
+  })
+})

package/src/connection.ts

@@ -0,0 +1,382 @@
+import net from 'node:net'
+import { randomUUID } from 'node:crypto'
+import { existsSync, readFileSync, unlinkSync } from 'node:fs'
+import path from 'node:path'
+import { stateDir } from './hash.ts'
+import type {
+  CommandRequest,
+  CommandResponse,
+  ServerMetadata,
+  TimeoutOptions,
+} from './types.ts'
+
+const DEFAULT_CONNECT_TIMEOUT = 5_000
+const DEFAULT_COMMAND_TIMEOUT = 30_000
+const DEFAULT_RECONNECT_TIMEOUT = 30_000
+const EXPECTED_PROTOCOL_VERSION = 1
+
+interface PendingRequest {
+  resolve: (value: CommandResponse) => void
+  reject: (reason?: unknown) => void
+  timer: NodeJS.Timeout
+}
+
+interface PipeConnectionOptions extends TimeoutOptions {
+  projectPath?: string
+}
+
+export class PipeConnection {
+  private socket: net.Socket | undefined
+  private connected = false
+  private intentionalDisconnect = false
+  private frameBuffer = Buffer.alloc(0)
+  private pending = new Map<string, PendingRequest>()
+  private pipePathValue: string | undefined
+  private connectInFlight: Promise<void> | undefined
+  private readonly connectTimeout: number
+  private readonly commandTimeout: number
+  private readonly reconnectTimeout: number
+  private readonly projectPath: string | undefined
+  private recoveryInFlight: Promise<void> | undefined
+
+  constructor(options: PipeConnectionOptions = {}) {
+    this.connectTimeout = options.connectTimeout ?? DEFAULT_CONNECT_TIMEOUT
+    this.commandTimeout = options.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT
+    this.reconnectTimeout = options.reconnectTimeout ?? DEFAULT_RECONNECT_TIMEOUT
+    this.projectPath = options.projectPath
+  }
+
+  async connect(pipePath: string): Promise<void> {
+    this.pipePathValue = pipePath
+    await this.ensureConnected(this.connectTimeout)
+  }
+
+  async send(request: CommandRequest): Promise<CommandResponse> {
+    if (!this.pipePathValue) {
+      throw new Error('Pipe path is not set. Call connect() before send().')
+    }
+
+    await this.ensureConnected(this.reconnectTimeout)
+
+    const timeout = this.commandTimeout
+    return new Promise<CommandResponse>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(request.id)
+        const fileResult = this.readResultFromDisk(request.id)
+        if (fileResult) {
+          resolve(fileResult)
+          return
+        }
+
+        reject(new Error(`Command timeout (${Math.round(timeout / 1000)}s) — the command may have hung Unity's main thread`))
+      }, timeout)
+
+      this.pending.set(request.id, { resolve, reject, timer })
+
+      try {
+        this.writeFrame(request)
+      } catch (error) {
+        clearTimeout(timer)
+        this.pending.delete(request.id)
+        reject(error)
+      }
+    })
+  }
+
+  disconnect(): void {
+    this.intentionalDisconnect = true
+    this.connected = false
+
+    if (this.socket) {
+      this.socket.destroy()
+      this.socket = undefined
+    }
+
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer)
+      pending.reject(new Error(`Connection closed before response for ${id}`))
+    }
+    this.pending.clear()
+    this.connectInFlight = undefined
+  }
+
+  serverMetadata(): ServerMetadata | null {
+    if (!this.projectPath) {
+      return null
+    }
+
+    const metadataPath = path.join(stateDir(this.projectPath), 'server.json')
+    if (!existsSync(metadataPath)) {
+      return null
+    }
+
+    try {
+      return JSON.parse(readFileSync(metadataPath, 'utf-8')) as ServerMetadata
+    } catch {
+      return null
+    }
+  }
+
+  private async ensureConnected(timeout: number): Promise<void> {
+    if (this.connected && this.socket && !this.socket.destroyed) {
+      return
+    }
+
+    if (!this.pipePathValue) {
+      throw new Error('Pipe path is not set. Call connect() before send().')
+    }
+
+    if (!this.connectInFlight) {
+      this.connectInFlight = this.connectWithRetry(this.pipePathValue, timeout)
+        .finally(() => {
+          this.connectInFlight = undefined
+        })
+    }
+
+    await this.connectInFlight
+  }
+
+  private async connectWithRetry(pipePath: string, timeout: number): Promise<void> {
+    const started = Date.now()
+    let delay = 200
+
+    while (Date.now() - started < timeout) {
+      try {
+        await this.connectOnce(pipePath)
+        this.validateProtocolVersion()
+        this.requestPendingResults()
+        return
+      } catch {
+        await sleep(delay)
+        delay = Math.min(delay * 2, 5_000)
+      }
+    }
+
+    throw new Error(`Connect timeout (${Math.round(timeout / 1000)}s) — is Unity open with the unibridge plugin loaded?`)
+  }
+
+  private connectOnce(pipePath: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const socket = net.connect({ path: pipePath })
+
+      const onError = (error: Error) => {
+        socket.removeListener('connect', onConnect)
+        reject(error)
+      }
+
+      const onConnect = () => {
+        socket.removeListener('error', onError)
+        this.socket = socket
+        this.connected = true
+        this.intentionalDisconnect = false
+        this.attachSocketHandlers(socket)
+        resolve()
+      }
+
+      socket.once('error', onError)
+      socket.once('connect', onConnect)
+    })
+  }
+
+  private attachSocketHandlers(socket: net.Socket): void {
+    socket.on('data', (chunk: Buffer | string) => {
+      if (typeof chunk !== 'string') {
+        this.frameBuffer = Buffer.concat([this.frameBuffer, chunk])
+      }
+      this.parseFrames()
+    })
+
+    socket.on('close', () => {
+      if (!this.intentionalDisconnect) {
+        this.connected = false
+        this.tryRecoverPending()
+      }
+    })
+
+    socket.on('error', () => {
+      this.connected = false
+      this.tryRecoverPending()
+    })
+  }
+
+  private parseFrames(): void {
+    while (this.frameBuffer.length >= 4) {
+      const messageLength = this.frameBuffer.readUInt32BE(0)
+      if (this.frameBuffer.length < 4 + messageLength) {
+        return
+      }
+
+      const rawMessage = this.frameBuffer.subarray(4, 4 + messageLength)
+      this.frameBuffer = this.frameBuffer.subarray(4 + messageLength)
+
+      if (rawMessage.length === 0) {
+        continue
+      }
+
+      let parsed: CommandResponse
+      try {
+        parsed = JSON.parse(rawMessage.toString()) as CommandResponse
+      } catch {
+        continue
+      }
+
+      const pending = this.pending.get(parsed.id)
+      if (pending) {
+        clearTimeout(pending.timer)
+        this.pending.delete(parsed.id)
+        this.deleteResultFile(parsed.id)
+        pending.resolve(parsed)
+        continue
+      }
+
+      this.tryResolveRecoveredPayload(parsed)
+    }
+  }
+
+  private writeFrame(payload: unknown): void {
+    if (!this.socket || this.socket.destroyed) {
+      throw new Error('Connection is not active')
+    }
+
+    const body = Buffer.from(JSON.stringify(payload), 'utf-8')
+    const frame = Buffer.alloc(4 + body.length)
+    frame.writeUInt32BE(body.length, 0)
+    body.copy(frame, 4)
+    this.socket.write(frame)
+  }
+
+  private validateProtocolVersion(): void {
+    const metadata = this.serverMetadata()
+    if (!metadata) {
+      return
+    }
+
+    if (metadata.protocolVersion !== EXPECTED_PROTOCOL_VERSION) {
+      throw new Error(
+        `Protocol version mismatch: SDK expects ${EXPECTED_PROTOCOL_VERSION}, Unity plugin is ${metadata.protocolVersion}`,
+      )
+    }
+  }
+
+  private requestPendingResults(): void {
+    if (!this.socket || this.socket.destroyed || this.pending.size === 0) {
+      return
+    }
+
+    this.writeFrame({
+      id: `recover-${randomUUID()}`,
+      command: 'recoverResults',
+      params: { ids: [...this.pending.keys()] },
+    })
+  }
+
+  private tryRecoverPending(): void {
+    if (this.pending.size === 0 || this.recoveryInFlight) {
+      return
+    }
+
+    this.recoveryInFlight = this.ensureConnected(this.reconnectTimeout)
+      .catch(() => {
+        // Per-request timeouts and file fallback will handle failure.
+      })
+      .finally(() => {
+        this.recoveryInFlight = undefined
+      })
+  }
+
+  private tryResolveRecoveredPayload(response: CommandResponse): void {
+    let payload: unknown = response.result
+    if (typeof payload === 'string') {
+      try {
+        payload = JSON.parse(payload)
+      } catch {
+        return
+      }
+    }
+
+    if (!payload || typeof payload !== 'object' || !('results' in payload)) {
+      return
+    }
+
+    const maybeResults = (payload as { results?: unknown }).results
+    if (!Array.isArray(maybeResults)) {
+      return
+    }
+
+    for (const item of maybeResults) {
+      if (!item || typeof item !== 'object' || !('id' in item) || typeof item.id !== 'string') {
+        continue
+      }
+      const recoveredItem = item as Partial<CommandResponse> & { id: string }
+
+      const pending = this.pending.get(recoveredItem.id)
+      if (!pending) {
+        continue
+      }
+
+      const recovered: CommandResponse = {
+        id: recoveredItem.id,
+        success: typeof recoveredItem.success === 'boolean' ? recoveredItem.success : false,
+        result: recoveredItem.result,
+        error: typeof recoveredItem.error === 'string' ? recoveredItem.error : undefined,
+      }
+
+      clearTimeout(pending.timer)
+      this.pending.delete(recoveredItem.id)
+      this.deleteResultFile(recoveredItem.id)
+      pending.resolve(recovered)
+    }
+  }
+
+  private readResultFromDisk(requestId: string): CommandResponse | null {
+    if (!this.projectPath) {
+      return null
+    }
+
+    const resultPath = path.join(stateDir(this.projectPath), 'results', `${requestId}.json`)
+    if (!existsSync(resultPath)) {
+      return null
+    }
+
+    try {
+      const parsed = JSON.parse(readFileSync(resultPath, 'utf-8')) as Partial<CommandResponse>
+      if (typeof parsed.id !== 'string' || parsed.id !== requestId) {
+        return null
+      }
+
+      const response: CommandResponse = {
+        id: parsed.id,
+        success: Boolean(parsed.success),
+        result: parsed.result,
+        error: typeof parsed.error === 'string' ? parsed.error : undefined,
+      }
+
+      this.deleteResultFile(requestId)
+
+      return response
+    } catch {
+      return null
+    }
+  }
+
+  private deleteResultFile(requestId: string): void {
+    if (!this.projectPath) {
+      return
+    }
+
+    const resultPath = path.join(stateDir(this.projectPath), 'results', `${requestId}.json`)
+    if (!existsSync(resultPath)) {
+      return
+    }
+
+    try {
+      unlinkSync(resultPath)
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/hash.test.ts

@@ -0,0 +1,48 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { pipePath, projectHash, stateDir } from './hash.ts'
+
+describe('projectHash', () => {
+  it('returns a 12-char hex string', () => {
+    const hash = projectHash('/Users/me/MyGame')
+    assert.equal(hash.length, 12)
+    assert.match(hash, /^[a-f0-9]{12}$/)
+  })
+
+  it('is deterministic', () => {
+    const a = projectHash('/Users/me/MyGame')
+    const b = projectHash('/Users/me/MyGame')
+    assert.equal(a, b)
+  })
+
+  it('differs for different paths', () => {
+    const a = projectHash('/Users/me/GameA')
+    const b = projectHash('/Users/me/GameB')
+    assert.notEqual(a, b)
+  })
+
+  it('normalizes trailing slash differences', () => {
+    const a = projectHash('/Users/me/MyGame')
+    const b = projectHash('/Users/me/MyGame/')
+    assert.equal(a, b)
+  })
+
+  it('handles paths with spaces', () => {
+    const hash = projectHash('/Users/me/My Game')
+    assert.match(hash, /^[a-f0-9]{12}$/)
+  })
+})
+
+describe('pipePath', () => {
+  it('returns a unix socket path on non-Windows', () => {
+    const path = pipePath('/Users/me/MyGame')
+    assert.match(path, /^\/tmp\/unibridge\/[a-f0-9]{12}\/bridge\.sock$/)
+  })
+})
+
+describe('stateDir', () => {
+  it('returns the temp directory for the project', () => {
+    const dir = stateDir('/Users/me/MyGame')
+    assert.match(dir, /^\/tmp\/unibridge\/[a-f0-9]{12}$/)
+  })
+})

package/src/hash.ts

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+function canonicalizeProjectPath(projectPath: string): string {
+  const resolved = path.resolve(projectPath)
+  let canonical = resolved
+
+  try {
+    canonical = realpathSync.native(resolved)
+  } catch {
+    // Fall back to the resolved path when it does not exist yet.
+  }
+
+  canonical = canonical.replace(/\\/g, '/')
+  canonical = canonical.replace(/\/+$/g, '')
+
+  if (process.platform === 'win32') {
+    canonical = canonical.toLowerCase()
+  }
+
+  return canonical
+}
+
+export function projectHash(projectPath: string): string {
+  const canonical = canonicalizeProjectPath(projectPath)
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 12)
+}
+
+function stateBaseDir(): string {
+  if (process.platform === 'win32') {
+    return path.join(os.tmpdir(), 'unibridge')
+  }
+
+  return '/tmp/unibridge'
+}
+
+export function stateDir(projectPath: string): string {
+  return path.join(stateBaseDir(), projectHash(projectPath))
+}
+
+export function pipePath(projectPath: string): string {
+  const hash = projectHash(projectPath)
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\unibridge-${hash}`
+  }
+
+  return path.join(stateBaseDir(), hash, 'bridge.sock')
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { init, findUnityProject, isPluginInstalled } from './project.ts'
+export { createClient } from './client.ts'
+export type * from './commands/contracts.ts'
+export type {
+  InitOptions,
+  InitResult,
+  CommandResponse,
+  ClientOptions,
+  UniBridgeClient,
+} from './types.ts'

package/src/project.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { findUnityProject, init, isPluginInstalled, parseUnityVersion } from './project.ts'
+
+const baseDir = '/tmp/unibridge-sdk-project-tests'
+const testDir = `${baseDir}/test-unity-project`
+const testDirWithSpaces = `${baseDir}/test unity project`
+
+function createFakeProject(path: string, version = '2022.3.10f1') {
+  mkdirSync(`${path}/Assets`, { recursive: true })
+  mkdirSync(`${path}/ProjectSettings`, { recursive: true })
+  mkdirSync(`${path}/Packages`, { recursive: true })
+  writeFileSync(`${path}/ProjectSettings/ProjectVersion.txt`, `m_EditorVersion: ${version}\n`)
+  writeFileSync(`${path}/Packages/manifest.json`, JSON.stringify({ dependencies: {} }, null, 2))
+}
+
+describe('findUnityProject', () => {
+  beforeEach(() => createFakeProject(testDir))
+  afterEach(() => rmSync(baseDir, { recursive: true, force: true }))
+
+  it('finds project at the given path', () => {
+    assert.equal(findUnityProject(testDir), testDir)
+  })
+
+  it('finds project from a subdirectory', () => {
+    mkdirSync(`${testDir}/Assets/Scripts`, { recursive: true })
+    assert.equal(findUnityProject(`${testDir}/Assets/Scripts`), testDir)
+  })
+
+  it('supports project paths with spaces', () => {
+    createFakeProject(testDirWithSpaces)
+    assert.equal(findUnityProject(testDirWithSpaces), testDirWithSpaces)
+  })
+
+  it('throws when no Unity project is found', () => {
+    assert.throws(() => findUnityProject('/tmp'), /Unity project not found/)
+  })
+})
+
+describe('parseUnityVersion', () => {
+  beforeEach(() => createFakeProject(testDir, '6000.0.23f1'))
+  afterEach(() => rmSync(baseDir, { recursive: true, force: true }))
+
+  it('extracts version string', () => {
+    assert.equal(parseUnityVersion(testDir), '6000.0.23f1')
+  })
+})
+
+describe('init', () => {
+  beforeEach(() => createFakeProject(testDir))
+  afterEach(() => rmSync(baseDir, { recursive: true, force: true }))
+
+  it('adds plugin to manifest.json with git source', async () => {
+    const result = await init({ projectPath: testDir })
+    assert.equal(result.unityVersion, '2022.3.10f1')
+    assert.equal(result.pluginSource, 'git')
+
+    const manifest = JSON.parse(readFileSync(`${testDir}/Packages/manifest.json`, 'utf-8'))
+    assert.ok(manifest.dependencies['com.msanatan.unibridge'])
+  })
+
+  it('adds plugin with local source', async () => {
+    const result = await init({
+      projectPath: testDir,
+      source: { type: 'local', path: '../unibridge/unity' },
+    })
+    assert.equal(result.pluginSource, 'local')
+
+    const manifest = JSON.parse(readFileSync(`${testDir}/Packages/manifest.json`, 'utf-8'))
+    assert.equal(manifest.dependencies['com.msanatan.unibridge'], 'file:../unibridge/unity')
+  })
+
+  it('no-ops when plugin is already at correct version', async () => {
+    await init({ projectPath: testDir })
+    const result = await init({ projectPath: testDir })
+    assert.equal(result.pluginSource, 'git')
+  })
+})
+
+describe('isPluginInstalled', () => {
+  beforeEach(() => createFakeProject(testDir))
+  afterEach(() => rmSync(baseDir, { recursive: true, force: true }))
+
+  it('returns false when dependency is absent', () => {
+    assert.equal(isPluginInstalled(testDir), false)
+  })
+
+  it('returns true after init installs the plugin', async () => {
+    await init({ projectPath: testDir })
+    assert.equal(isPluginInstalled(testDir), true)
+  })
+})

package/src/project.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { cwd } from 'node:process'
+import type { InitOptions, InitResult } from './types.ts'
+
+const PLUGIN_NAME = 'com.msanatan.unibridge'
+
+const SDK_VERSION = (
+  JSON.parse(
+    readFileSync(path.join(import.meta.dirname, '..', 'package.json'), 'utf-8'),
+  ) as { version: string }
+).version
+
+const DEFAULT_GIT_SOURCE =
+  `https://github.com/msanatan/unibridge.git?path=unity#v${SDK_VERSION}`
+
+interface Manifest {
+  dependencies?: Record<string, string>
+}
+
+function readManifest(projectPath: string): Manifest {
+  const manifestPath = path.join(projectPath, 'Packages', 'manifest.json')
+  return JSON.parse(readFileSync(manifestPath, 'utf-8')) as Manifest
+}
+
+function writeManifestAtomic(projectPath: string, manifest: Manifest): void {
+  const manifestPath = path.join(projectPath, 'Packages', 'manifest.json')
+  const tempPath = `${manifestPath}.tmp`
+  const content = `${JSON.stringify(manifest, null, 2)}\n`
+  writeFileSync(tempPath, content, 'utf-8')
+  renameSync(tempPath, manifestPath)
+}
+
+export function findUnityProject(startPath: string = cwd()): string {
+  let current = path.resolve(startPath)
+
+  while (true) {
+    const assetsPath = path.join(current, 'Assets')
+    const versionPath = path.join(current, 'ProjectSettings', 'ProjectVersion.txt')
+
+    if (existsSync(assetsPath) && existsSync(versionPath)) {
+      return current
+    }
+
+    const parent = path.dirname(current)
+    if (parent === current) {
+      throw new Error('Unity project not found. Run inside a Unity project or pass --project <path>.')
+    }
+
+    current = parent
+  }
+}
+
+export function parseUnityVersion(projectPath: string): string {
+  const versionPath = path.join(projectPath, 'ProjectSettings', 'ProjectVersion.txt')
+  const content = readFileSync(versionPath, 'utf-8')
+  const match = content.match(/m_EditorVersion:\s*(\S+)/)
+  if (!match) {
+    throw new Error(`Could not parse m_EditorVersion from ${versionPath}`)
+  }
+
+  return match[1]
+}
+
+export function isPluginInstalled(projectPath: string): boolean {
+  const manifest = readManifest(projectPath)
+  return Boolean(manifest.dependencies?.[PLUGIN_NAME])
+}
+
+export async function init(options: InitOptions = {}): Promise<InitResult> {
+  const projectPath = findUnityProject(options.projectPath)
+  const unityVersion = parseUnityVersion(projectPath)
+
+  const manifest = readManifest(projectPath)
+  const dependencies = { ...(manifest.dependencies ?? {}) }
+
+  const pluginSource = options.source?.type ?? 'git'
+  const pluginReference =
+    options.source?.type === 'local'
+      ? `file:${options.source.path}`
+      : options.source?.type === 'git'
+        ? options.source.url
+        : DEFAULT_GIT_SOURCE
+
+  if (dependencies[PLUGIN_NAME] !== pluginReference) {
+    dependencies[PLUGIN_NAME] = pluginReference
+    writeManifestAtomic(projectPath, {
+      ...manifest,
+      dependencies,
+    })
+  }
+
+  return {
+    projectPath,
+    unityVersion,
+    pluginVersion: SDK_VERSION,
+    pluginSource,
+  }
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+import type { CommandMethods } from './commands/define.ts'
+import type { allCommands } from './commands/registry.ts'
+
+export interface InitOptions {
+  projectPath?: string
+  source?: GitSource | LocalSource
+}
+
+export interface GitSource {
+  type: 'git'
+  url: string
+}
+
+export interface LocalSource {
+  type: 'local'
+  path: string
+}
+
+export interface InitResult {
+  projectPath: string
+  unityVersion: string
+  pluginVersion: string
+  pluginSource: 'git' | 'local'
+}
+
+export interface CommandRequest {
+  id: string
+  command: string
+  params: Record<string, unknown>
+}
+
+export interface CommandResponse {
+  id: string
+  success: boolean
+  result?: unknown
+  error?: string
+}
+
+export interface ServerMetadata {
+  pid: number
+  unityVersion: string
+  pluginVersion: string
+  protocolVersion: number
+  capabilities?: {
+    executeEnabled?: boolean
+  }
+  projectPath?: string
+}
+
+export interface TimeoutOptions {
+  connectTimeout?: number
+  commandTimeout?: number
+  reconnectTimeout?: number
+}
+
+export interface ClientOptions extends TimeoutOptions {
+  projectPath?: string
+  enableExecute?: boolean
+}
+
+export type UniBridgeClient = CommandMethods<typeof allCommands> & {
+  readonly projectPath: string
+  close(): void
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "src/**/*.test.ts"
+  ]
+}