feat(devframe): add onServerError to observe post-bind server errors

startHttpAndWs's owned httpServer has no error listener once past the
bind window this PR's base fixes — the temporary listener is removed
the instant listen() succeeds. A later runtime error (e.g. a
transient EMFILE while accepting a connection) still crashes the
process, and StartedServer exposes no handle a caller could attach
their own listener to (unlike the shared-server path, where the
caller already owns the object).

Add an onServerError option instead of exposing the raw httpServer —
handing out the raw object would let a caller call close() on it
directly, bypassing the wrapper's close() and leaking the WS
transport exactly like the bug this PR's base fixes. The callback
fires for the bind-time error too (alongside the rejection), so it's
one place to observe every error the server ever emits, bind or
lifetime.

The lifetime-forwarding wire-up (httpServer.on('error', ...)) is a
one-line, logic-free pass-through of Node's own documented event and
isn't covered by a dedicated test: StartedServer deliberately doesn't
expose the raw server, so a test has no way to trigger a genuine
post-bind error without a test-only seam.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: dvcolomban

packages/devframe/src/node/__tests__/server.test.ts

@@ -115,4 +115,22 @@ describe('startHttpAndWs listen failures', () => {
       await first.close()
     }
   })
+
+  it('forwards the bind error to onServerError alongside the rejection', async () => {
+    const host = '127.0.0.1'
+    const first = await startHttpAndWs({ context: await createTestContext(), host, port: 0, auth: false })
+    const onServerError = vi.fn()
+
+    try {
+      await expect(
+        startHttpAndWs({ context: await createTestContext(), host, port: first.port, auth: false, onServerError }),
+      ).rejects.toThrow(expect.objectContaining({ code: 'DF0052' }))
+
+      expect(onServerError).toHaveBeenCalledOnce()
+      expect((onServerError.mock.calls[0]![0] as Error & { code?: string }).code).toBe('EADDRINUSE')
+    }
+    finally {
+      await first.close()
+    }
+  })
 })

packages/devframe/src/node/server.ts

@@ -109,6 +109,16 @@ export interface StartHttpAndWsOptions {
    * own startup banner. Devframe does not print one itself.
    */
   onReady?: (info: { origin: string, port: number, app: H3 }) => void | Promise<void>
+  /**
+   * Called for every error the owned HTTP server emits — during the initial
+   * bind (alongside the rejection `startHttpAndWs` already throws for that
+   * case) and for any error afterward, for the server's whole running life
+   * (e.g. a transient `EMFILE` while accepting a connection). Ignored when a
+   * `server` is supplied — the caller already owns that object and can
+   * listen on it directly. Without this, a post-bind error has no listener
+   * and crashes the process, matching today's behavior.
+   */
+  onServerError?: (error: Error) => void
 }
 
 export interface StartedServer {
@@ -256,7 +266,10 @@ export async function startHttpAndWs(options: StartHttpAndWsOptions): Promise<St
   if (ownsHttpServer) {
     try {
       await new Promise<void>((resolve, reject) => {
-        const onError = (error: Error): void => reject(error)
+        const onError = (error: Error): void => {
+          options.onServerError?.(error)
+          reject(error)
+        }
         // Without this listener a failed bind emits `error` with nobody
         // attached — an uncaughtException — and the `listen` callback never
         // fires, so this promise never settles.
@@ -273,6 +286,12 @@ export async function startHttpAndWs(options: StartHttpAndWsOptions): Promise<St
       await closeWs().catch(() => {})
       throw diagnostics.DF0052({ host: bindHost, port, reason: (error as Error).message, cause: error as Error })
     }
+    // The bind succeeded, so the temporary listener above is gone. Attach a
+    // persistent one for the server's remaining life — otherwise a later
+    // error (e.g. a transient EMFILE while accepting a connection) has no
+    // listener and crashes the process the same way an unguarded bind used to.
+    if (options.onServerError)
+      httpServer.on('error', options.onServerError)
   }
 
   const address = httpServer.address()