Function createHelperClient

apps/desktop/src/main/helper/client.ts:131–303

(
  opts: CreateHelperClientOptions,
)

 * helper reports a different protocol version, so B-3 can trigger a re-install.
 */
export function createHelperClient(
  opts: CreateHelperClientOptions,
): HelperClient {
  const { socketPath, secret, onDisconnect } = opts
  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
  const closeTimeoutMs = opts.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS

  // FIFO queue of in-flight requests awaiting their response frame.
  interface Pending {
    resolve: (res: HelperResponse) => void
    reject: (err: Error) => void
    timer: ReturnType<typeof setTimeout>
  }
  const pending: Pending[] = []
  let buffer = ''
  /** Set once the socket dies so later requests fail fast instead of hanging. */
  let fatal: Error | undefined
  /** Set when WE end the socket so the close/error isn't read as a crash. */
  let closing = false
  /** Guards onDisconnect to fire at most once (error + close can both arrive). */
  let disconnected = false

  /**
   * Notify the owner of an UNEXPECTED drop exactly once. A deliberate `close()`
   * sets `closing` first, so the resulting close/error is never misreported as a
   * helper crash. No-op when no callback was supplied (sidecar callers).
   */
  function reportDisconnect(err?: Error): void {
    if (closing || disconnected) return
    disconnected = true
    onDisconnect?.(err)
  }

  const socket: Socket = connect(socketPath)
  socket.setEncoding('utf8')

  socket.on('data', (chunk: string) => {
    buffer += chunk
    const { messages, rest } = parseMessages<HelperResponse>(buffer)
    buffer = rest
    for (const res of messages) {
      const next = pending.shift()
      if (!next) continue
      clearTimeout(next.timer)
      if (res.ok) {
        next.resolve(res)
      } else {
        // Surface the server's failure — never swallow it.
        next.reject(
          new HelperRequestError(
            (res as { error?: string }).error ?? 'helper: request failed',
            res.type,
          ),
        )
      }
    }
  })