afm-bridge 0.1.0

package/src/node/index.ts

@@ -0,0 +1,203 @@
+import { type ChildProcess, spawn } from 'node:child_process'
+import { accessSync, chmodSync, constants, existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { ModelUnavailableError, TransportError } from '../errors.js'
+import { type Connection, createLineSplitter, type Transport, type TransportHandlers } from '../transport.js'
+
+export interface NodeStdioTransportOptions {
+  /** Path to `afm-bridge-server`. Default: `resolveSidecarPath()`. */
+  binaryPath?: string
+  args?: string[]
+  /** Extra environment variables for the sidecar. */
+  env?: Record<string, string | undefined>
+  /** Sidecar log level (stderr). Default `warn`. */
+  logLevel?: 'error' | 'warn' | 'info' | 'debug'
+  /** How long `close()` waits for a graceful exit before killing. Default 2000 ms. */
+  shutdownTimeoutMs?: number
+}
+
+/**
+ * Runs the sidecar as a child process and talks over stdin/stdout.
+ * Works in Electron's main process, plain Node and CLI tools.
+ */
+export class NodeStdioTransport implements Transport {
+  constructor(private readonly options: NodeStdioTransportOptions = {}) {}
+
+  async connect(handlers: TransportHandlers): Promise<Connection> {
+    assertSupportedPlatform()
+    const binary = this.options.binaryPath ?? resolveSidecarPath()
+    const child = spawn(binary, this.options.args ?? [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, AFM_BRIDGE_LOG: this.options.logLevel ?? 'warn', ...this.options.env },
+    })
+
+    await new Promise<void>((resolve, reject) => {
+      child.once('spawn', resolve)
+      child.once('error', (error) =>
+        reject(
+          new TransportError(`Could not start afm-bridge-server at ${binary}: ${error.message}`, {
+            type: 'transportError',
+            cause: error,
+          }),
+        ),
+      )
+    })
+
+    let exited = false
+    const exit = new Promise<void>((resolve) => {
+      child.once('close', (code, signal) => {
+        exited = true
+        stdout.flush()
+        stderr.flush()
+        handlers.onClose({ code, signal })
+        resolve()
+      })
+    })
+    // Errors after spawn (e.g. EPIPE on a dead process) surface through 'close'.
+    child.on('error', () => {})
+    child.stdin?.on('error', () => {})
+
+    const stdout = createLineSplitter((line) => handlers.onMessage(line))
+    const stderr = createLineSplitter((line) => handlers.onLog?.(line))
+    child.stdout?.setEncoding('utf8').on('data', (chunk: string) => stdout.push(chunk))
+    child.stderr?.setEncoding('utf8').on('data', (chunk: string) => stderr.push(chunk))
+
+    const shutdownTimeoutMs = this.options.shutdownTimeoutMs ?? 2000
+    return {
+      send(line) {
+        if (!exited && child.stdin?.writable) child.stdin.write(`${line}\n`)
+      },
+      async close() {
+        if (exited) return
+        setActive(child, true)
+        child.stdin?.end()
+        if (await settlesWithin(exit, shutdownTimeoutMs)) return
+        child.kill('SIGTERM')
+        if (await settlesWithin(exit, 1000)) return
+        child.kill('SIGKILL')
+        await exit
+      },
+      setActive(active) {
+        if (!exited) setActive(child, active)
+      },
+    }
+  }
+}
+
+/**
+ * Finds the `afm-bridge-server` binary. Order:
+ * 1. `AFM_BRIDGE_BINARY` environment variable
+ * 2. Packaged Electron app: `<app>/Contents/Resources/afm-bridge-server` (`process.resourcesPath`)
+ * 3. The `afm-bridge-darwin-arm64` package (with `app.asar` rewritten to `app.asar.unpacked`)
+ */
+export function resolveSidecarPath(): string {
+  const tried: string[] = []
+  const usable = (candidate: string) => {
+    tried.push(candidate)
+    try {
+      accessSync(candidate, constants.X_OK)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  const fromEnv = process.env.AFM_BRIDGE_BINARY
+  if (fromEnv) {
+    if (usable(fromEnv)) return fromEnv
+    throw notFound(tried, 'AFM_BRIDGE_BINARY points to a file that does not exist or is not executable.')
+  }
+
+  const resourcesPath = (process as { resourcesPath?: string }).resourcesPath
+  if (resourcesPath) {
+    const packaged = join(resourcesPath, 'afm-bridge-server')
+    if (usable(packaged)) return packaged
+  }
+
+  try {
+    const fromPackage = createRequire(import.meta.url).resolve(
+      'afm-bridge-darwin-arm64/bin/afm-bridge-server',
+    )
+    const unpacked = fromPackage.replace(/app\.asar([\\/])/, 'app.asar.unpacked$1')
+    if (unpacked !== fromPackage && usable(unpacked)) return unpacked
+    if (usable(fromPackage)) return fromPackage
+    // Some package managers drop the executable bit when installing; restore it.
+    if (unpacked === fromPackage && existsSync(fromPackage)) {
+      try {
+        chmodSync(fromPackage, 0o755)
+        if (usable(fromPackage)) return fromPackage
+      } catch {
+        // Read-only location; fall through to the error below.
+      }
+    }
+  } catch {
+    // Package not installed (not on macOS arm64, or optional dependencies were skipped).
+  }
+
+  throw notFound(tried)
+}
+
+function notFound(tried: string[], hint?: string): TransportError {
+  return new TransportError(
+    [
+      'afm-bridge-server binary not found.',
+      hint,
+      tried.length > 0 ? `Tried: ${tried.join(', ')}.` : undefined,
+      'Fix: install afm-bridge-darwin-arm64 (npm adds it automatically on Apple silicon), build it with `swift build -c release` and pass `binaryPath`, or set AFM_BRIDGE_BINARY.',
+    ]
+      .filter(Boolean)
+      .join(' '),
+    { type: 'transportError' },
+  )
+}
+
+/** Throws `ModelUnavailableError` on platforms where the sidecar cannot run. */
+function assertSupportedPlatform() {
+  if (process.platform !== 'darwin' || process.arch !== 'arm64') {
+    throw new ModelUnavailableError(
+      `Apple Foundation Models need macOS on Apple silicon (this is ${process.platform}/${process.arch})`,
+      { type: 'modelUnavailable', data: { model: 'on-device', reason: 'unsupportedPlatform' } },
+    )
+  }
+  const version = macOSVersion()
+  if (version !== undefined && version < 26) {
+    throw new ModelUnavailableError(
+      `Apple Foundation Models need macOS 26 or newer (this is macOS ${version})`,
+      {
+        type: 'modelUnavailable',
+        data: { model: 'on-device', reason: 'unsupportedOS' },
+      },
+    )
+  }
+}
+
+function macOSVersion(): number | undefined {
+  try {
+    const plist = readFileSync('/System/Library/CoreServices/SystemVersion.plist', 'utf8')
+    const match = /<key>ProductVersion<\/key>\s*<string>(\d+)/.exec(plist)
+    return match?.[1] ? Number(match[1]) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function setActive(child: ChildProcess, active: boolean) {
+  for (const handle of [child, child.stdin, child.stdout, child.stderr] as Array<{
+    ref?: () => void
+    unref?: () => void
+  } | null>) {
+    if (active) handle?.ref?.()
+    else handle?.unref?.()
+  }
+}
+
+async function settlesWithin(promise: Promise<void>, ms: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => resolve(false), ms)
+  })
+  const result = await Promise.race([promise.then(() => true), timeout])
+  clearTimeout(timer)
+  return result
+}

package/src/rpc.ts

@@ -0,0 +1,204 @@
+import {
+  AbortError,
+  AfmError,
+  errorFromRpc,
+  ProtocolError,
+  RequestTimeoutError,
+  type RpcErrorPayload,
+} from './errors.js'
+import type { Connection } from './transport.js'
+
+export interface RequestOptions {
+  signal?: AbortSignal | undefined
+  timeoutMs?: number | undefined
+  /** Called with the request id right before the request is written. */
+  onStart?: (id: number) => void
+  /** How long to wait for the peer to confirm a cancel before rejecting anyway. Default 5000 ms. */
+  cancelGraceMs?: number
+}
+
+type IncomingRequestHandler = (method: string, params: unknown, signal: AbortSignal) => Promise<unknown>
+
+interface Pending {
+  resolve(value: unknown): void
+  reject(error: unknown): void
+  cleanup(): void
+}
+
+const DEFAULT_CANCEL_GRACE_MS = 5000
+
+/** JSON-RPC 2.0 peer over one connection. Both sides can send requests. */
+export class RpcPeer {
+  private nextId = 1
+  private readonly pending = new Map<number, Pending>()
+  private readonly incoming = new Map<string | number, AbortController>()
+  private closedError: Error | undefined
+
+  constructor(
+    private readonly connection: Connection,
+    private readonly handlers: {
+      onNotification(method: string, params: unknown): void
+      onRequest?: IncomingRequestHandler
+      onPendingChange?(count: number): void
+      onProtocolError?(error: Error): void
+    },
+  ) {}
+
+  get pendingCount(): number {
+    return this.pending.size
+  }
+
+  request<T>(method: string, params: unknown, options: RequestOptions = {}): Promise<T> {
+    if (this.closedError) return Promise.reject(this.closedError)
+    const { signal, timeoutMs } = options
+    if (signal?.aborted) return Promise.reject(new AbortError())
+
+    const id = this.nextId++
+    return new Promise<T>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      let graceTimer: ReturnType<typeof setTimeout> | undefined
+      let cancelError: AfmError | undefined
+
+      const cancel = (error: AfmError) => {
+        if (cancelError || !this.pending.has(id)) return
+        cancelError = error
+        this.notify('cancel', { id })
+        // Wait for the sidecar's answer so the session is free again when we reject,
+        // but never hang if the sidecar does not answer.
+        const grace = options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS
+        if (grace <= 0) this.settle(id, { error })
+        else graceTimer = setTimeout(() => this.settle(id, { error }), grace)
+      }
+      const onAbort = () => cancel(new AbortError())
+
+      this.pending.set(id, {
+        resolve: (value) => resolve(value as T),
+        // A cancelled request is answered with `cancelled`; report the reason we cancelled for.
+        reject: (error) =>
+          reject(
+            cancelError && error instanceof AfmError && error.type === 'cancelled' ? cancelError : error,
+          ),
+        cleanup: () => {
+          if (timer) clearTimeout(timer)
+          if (graceTimer) clearTimeout(graceTimer)
+          signal?.removeEventListener('abort', onAbort)
+        },
+      })
+      this.handlers.onPendingChange?.(this.pending.size)
+
+      signal?.addEventListener('abort', onAbort, { once: true })
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(
+          () => cancel(new RequestTimeoutError(`Request '${method}' timed out after ${timeoutMs} ms`)),
+          timeoutMs,
+        )
+      }
+      options.onStart?.(id)
+      this.write({ jsonrpc: '2.0', id, method, params })
+    })
+  }
+
+  notify(method: string, params: unknown): void {
+    if (this.closedError) return
+    this.write({ jsonrpc: '2.0', method, params })
+  }
+
+  /** Feeds one line received from the connection. */
+  handleLine(line: string): void {
+    let message: Record<string, unknown>
+    try {
+      message = JSON.parse(line)
+    } catch {
+      this.handlers.onProtocolError?.(new ProtocolError(`Sidecar sent invalid JSON: ${line.slice(0, 200)}`))
+      return
+    }
+    if (typeof message !== 'object' || message === null || message.jsonrpc !== '2.0') {
+      this.handlers.onProtocolError?.(
+        new ProtocolError(`Sidecar sent a non JSON-RPC message: ${line.slice(0, 200)}`),
+      )
+      return
+    }
+    const { id, method } = message
+    if (typeof method === 'string') {
+      if (id === undefined) this.handleNotification(method, message.params)
+      else this.handleIncomingRequest(id as string | number, method, message.params)
+      return
+    }
+    if (typeof id === 'number') {
+      if ('error' in message) this.settle(id, { error: errorFromRpc(message.error as RpcErrorPayload) })
+      else this.settle(id, { result: message.result })
+      return
+    }
+    // Error without id: the sidecar could not parse something we sent.
+    if ('error' in message) this.handlers.onProtocolError?.(errorFromRpc(message.error as RpcErrorPayload))
+  }
+
+  /** Rejects everything in flight; later calls reject with the same error. */
+  close(error: Error): void {
+    if (this.closedError) return
+    this.closedError = error
+    for (const id of [...this.pending.keys()]) this.settle(id, { error })
+    for (const controller of this.incoming.values()) controller.abort()
+    this.incoming.clear()
+  }
+
+  private handleNotification(method: string, params: unknown) {
+    if (method === 'cancel') {
+      const id = (params as { id?: string | number } | undefined)?.id
+      if (id !== undefined) this.incoming.get(id)?.abort()
+      return
+    }
+    this.handlers.onNotification(method, params)
+  }
+
+  private handleIncomingRequest(id: string | number, method: string, params: unknown) {
+    const handler = this.handlers.onRequest
+    if (!handler) {
+      this.write({
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: `Method not found: ${method}`, data: { type: 'methodNotFound' } },
+      })
+      return
+    }
+    const controller = new AbortController()
+    this.incoming.set(id, controller)
+    handler(method, params, controller.signal).then(
+      (result) => {
+        this.incoming.delete(id)
+        this.write({ jsonrpc: '2.0', id, result })
+      },
+      (error: unknown) => {
+        this.incoming.delete(id)
+        const payload =
+          error instanceof AfmError && error.code !== undefined
+            ? { code: error.code, message: error.message, data: { ...error.data, type: error.type } }
+            : {
+                code: -32000,
+                message: error instanceof Error ? error.message : String(error),
+                data: { type: 'handlerError' },
+              }
+        this.write({ jsonrpc: '2.0', id, error: payload })
+      },
+    )
+  }
+
+  private settle(id: number, outcome: { result?: unknown; error?: unknown }) {
+    const entry = this.pending.get(id)
+    if (!entry) return
+    this.pending.delete(id)
+    entry.cleanup()
+    this.handlers.onPendingChange?.(this.pending.size)
+    if ('error' in outcome && outcome.error !== undefined) entry.reject(outcome.error)
+    else entry.resolve(outcome.result)
+  }
+
+  private write(message: unknown) {
+    if (this.closedError) return
+    try {
+      this.connection.send(JSON.stringify(message))
+    } catch (error) {
+      this.handlers.onProtocolError?.(error instanceof Error ? error : new Error(String(error)))
+    }
+  }
+}

package/src/schema.ts

@@ -0,0 +1,206 @@
+import { DecodingError } from './errors.js'
+
+/** The JSON Schema subset afm-bridge supports (PROTOCOL.md section 8). */
+export interface JSONSchema {
+  type?: 'object' | 'array' | 'string' | 'integer' | 'number' | 'boolean' | 'null' | Array<string>
+  description?: string
+  properties?: Record<string, JSONSchema>
+  required?: string[]
+  additionalProperties?: false
+  items?: JSONSchema
+  minItems?: number
+  maxItems?: number
+  minimum?: number
+  maximum?: number
+  enum?: Array<string | null>
+  const?: string
+  pattern?: string
+  anyOf?: JSONSchema[]
+  oneOf?: JSONSchema[]
+  $ref?: string
+  $defs?: Record<string, JSONSchema>
+  definitions?: Record<string, JSONSchema>
+  [annotation: string]: unknown
+}
+
+const structured = Symbol.for('afm-bridge.schema')
+
+/**
+ * A schema plus a parser that turns the generated JSON into `T`. Create one with
+ * `jsonSchema()` or `zodSchema()` from `afm-bridge/zod`.
+ */
+export interface StructuredSchema<T> {
+  readonly [structured]: true
+  readonly jsonSchema: JSONSchema
+  /** Validates and converts a generated value. Throws `DecodingError` when it does not match. */
+  parse(value: unknown): T
+}
+
+/** A plain JSON Schema object or a `StructuredSchema`. */
+export type SchemaInput<T = unknown> = JSONSchema | StructuredSchema<T>
+
+/**
+ * Wraps a JSON Schema. Without `parse` the result is checked by the built-in validator
+ * for the supported subset and typed as `T`.
+ */
+export function jsonSchema<T = unknown>(
+  schema: JSONSchema,
+  parse?: (value: unknown) => T,
+): StructuredSchema<T> {
+  return {
+    [structured]: true,
+    jsonSchema: schema,
+    parse:
+      parse ??
+      ((value: unknown) => {
+        const issue = validate(schema, value)
+        if (issue) {
+          throw new DecodingError(
+            `Generated value does not match the schema at '${issue.path}': ${issue.message}`,
+            {
+              type: 'decodingFailure',
+              data: { path: issue.path, rawContent: JSON.stringify(value) },
+            },
+          )
+        }
+        return value as T
+      }),
+  }
+}
+
+export function isStructuredSchema(value: unknown): value is StructuredSchema<unknown> {
+  return typeof value === 'object' && value !== null && structured in value
+}
+
+export function toStructuredSchema<T>(input: SchemaInput<T>): StructuredSchema<T> {
+  return isStructuredSchema(input) ? (input as StructuredSchema<T>) : jsonSchema<T>(input as JSONSchema)
+}
+
+/** Recursively optional, for partial values while a structured response streams in. */
+export type DeepPartial<T> =
+  T extends Array<infer U>
+    ? Array<DeepPartial<U>>
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T
+
+// MARK: - Validation of the supported subset
+
+interface Issue {
+  path: string
+  message: string
+}
+
+/** Returns the first mismatch between `value` and `schema`, or undefined. `format` is not checked. */
+export function validate(schema: JSONSchema, value: unknown): Issue | undefined {
+  return check(schema, value, '#', schema, 0)
+}
+
+function check(
+  schema: JSONSchema,
+  value: unknown,
+  path: string,
+  root: JSONSchema,
+  depth: number,
+): Issue | undefined {
+  if (depth > 64) return undefined
+  const fail = (message: string): Issue => ({ path, message })
+
+  if (schema.$ref !== undefined) {
+    const target = resolveRef(schema.$ref, root)
+    if (!target) return fail(`cannot resolve ${schema.$ref}`)
+    return check(target, value, path, root, depth + 1)
+  }
+  const branches = schema.anyOf ?? schema.oneOf
+  if (branches) {
+    const ok = branches.some((b) => !check(b, value, path, root, depth + 1))
+    return ok ? undefined : fail('does not match any of the allowed schemas')
+  }
+  if (schema.enum) {
+    return schema.enum.includes(value as string | null)
+      ? undefined
+      : fail(`must be one of ${JSON.stringify(schema.enum)}`)
+  }
+  if (schema.const !== undefined) {
+    return value === schema.const ? undefined : fail(`must be ${JSON.stringify(schema.const)}`)
+  }
+
+  const types = schema.type === undefined ? [] : Array.isArray(schema.type) ? schema.type : [schema.type]
+  if (value === null) {
+    return types.includes('null') ? undefined : fail('must not be null')
+  }
+  const type = types.find((t) => t !== 'null')
+  switch (type) {
+    case 'string': {
+      if (typeof value !== 'string') return fail('must be a string')
+      // A pattern that is valid for Swift but not for JavaScript is skipped, not failed.
+      const pattern = schema.pattern === undefined ? undefined : safeRegExp(schema.pattern)
+      if (pattern && !pattern.test(value)) return fail(`must match /${schema.pattern}/`)
+      return undefined
+    }
+    case 'integer':
+    case 'number':
+      if (typeof value !== 'number' || !Number.isFinite(value)) return fail(`must be a ${type}`)
+      if (type === 'integer' && !Number.isInteger(value)) return fail('must be an integer')
+      if (schema.minimum !== undefined && value < schema.minimum) return fail(`must be >= ${schema.minimum}`)
+      if (schema.maximum !== undefined && value > schema.maximum) return fail(`must be <= ${schema.maximum}`)
+      return undefined
+    case 'boolean':
+      return typeof value === 'boolean' ? undefined : fail('must be a boolean')
+    case 'array': {
+      if (!Array.isArray(value)) return fail('must be an array')
+      if (schema.minItems !== undefined && value.length < schema.minItems) {
+        return fail(`must have at least ${schema.minItems} items`)
+      }
+      if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+        return fail(`must have at most ${schema.maxItems} items`)
+      }
+      if (!schema.items) return undefined
+      for (const [i, item] of value.entries()) {
+        const issue = check(schema.items, item, `${path}/${i}`, root, depth + 1)
+        if (issue) return issue
+      }
+      return undefined
+    }
+    case 'object': {
+      if (typeof value !== 'object' || Array.isArray(value)) return fail('must be an object')
+      const record = value as Record<string, unknown>
+      const properties = schema.properties ?? {}
+      for (const key of schema.required ?? []) {
+        if (!(key in record)) return fail(`is missing required property '${key}'`)
+      }
+      for (const [key, v] of Object.entries(record)) {
+        const sub = properties[key]
+        if (!sub) {
+          if (schema.additionalProperties === false) return fail(`has unexpected property '${key}'`)
+          continue
+        }
+        const issue = check(sub, v, `${path}/${escapePointer(key)}`, root, depth + 1)
+        if (issue) return issue
+      }
+      return undefined
+    }
+    default:
+      return undefined
+  }
+}
+
+function resolveRef(ref: string, root: JSONSchema): JSONSchema | undefined {
+  if (ref === '#') return root
+  const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref)
+  if (!match?.[1] || !match[2]) return undefined
+  const defs = (match[1] === '$defs' ? root.$defs : root.definitions) ?? {}
+  return defs[match[2].replace(/~1/g, '/').replace(/~0/g, '~')]
+}
+
+function escapePointer(key: string): string {
+  return key.replace(/~/g, '~0').replace(/\//g, '~1')
+}
+
+function safeRegExp(pattern: string): RegExp | undefined {
+  try {
+    return new RegExp(pattern, 'u')
+  } catch {
+    return undefined
+  }
+}