/**
 * `RemoteServer` and `RemoteServerHandle` — output shapes for the SDK server.
 *
 * `RemoteServer` is what `createRemoteServer` returns: the assembled Hono
 * app plus a Node convenience helper. `RemoteServerHandle` is what `start()`
 * resolves to: the bound port and a `close()` function for graceful shutdown.
 */

import type { Hono } from 'hono'

export type RemoteServer = {
  /**
   * The assembled Hono app. Use `app.fetch` for any runtime
   * (Bun, Deno, Cloudflare Workers, or Node via `@hono/node-server`).
   */
  app: Hono
  /**
   * The worker's canonical serving URL — its `iss` identity (full URL, trailing
   * slash stripped, base path preserved). The single value the dispatcher signs
   * with and the kernel pins. Read it to seed `Identity.iss` on graph nodes so
   * the seeded value matches the signing issuer (never re-derive from a raw env).
   */
  iss: string
  /**
   * Convenience helper: start a Node HTTP server on the given port using
   * `@hono/node-server` (loaded via dynamic import). For other runtimes,
   * use `app.fetch` directly.
   */
  start: (port?: number) => Promise<RemoteServerHandle>
}

export type RemoteServerHandle = {
  /** The port the server is listening on (resolved even if `port: 0` was requested). */
  port: number
  /** Stop the server and release the port. */
  close: () => Promise<void>
}