feat(imap-server): notify(mailboxId, count) API for IDLE push

[ssilvius]

Summary

Adds a public notify(mailboxId, newMessageCount) method to @rafters/mail-imap-server so inbound email handlers can push RFC 2177 EXISTS responses to IDLE clients bound to a specific mailbox. Matches feature parity with @rafters/mail-imap-cloudflare, which has an equivalent inbound signal via POST /notify?count=N on its Durable Object. Until this PR the Node runtime had no way to wake IDLE clients when new mail arrived, and the docs promised a notification mechanism that did not exist.

Also fixes three real errors in the copied docs found during doc review.

API change

interface ImapServer {
  listen(): Promise<void>;
  close(): Promise<void>;
  readonly connections: number;
  readonly port: number | null;                              // NEW
  notify(mailboxId: string, newMessageCount: number): void;  // NEW
}

• notify -- delivers an EXISTS response to every session that is (a) currently in IDLE state and (b) bound to the specified mailbox. Sessions on other mailboxes and sessions not in IDLE are not affected. newMessageCount is the total for the mailbox after the insertion, not a delta.
• port -- returns the actual bound port after listen() resolves. Useful when the server starts on port 0 (ephemeral) and the caller needs the assigned port. Critical for test harnesses.

Implementation

Internal bookkeeping switched from a counter (let activeConnections = 0) to a typed Set<ConnectionEntry> ({ socket, state }). The switch is required to iterate connections inside notify() and filter by mailboxId + idleState. The connections getter still returns the set size so external API surface is unchanged.

Tests (5 new, 10 total)

All in packages/imap-server/tests/server.test.ts:

• surface check: notify exists on the returned object
• notify with no active connections does not throw
• notify with count = 0 does not throw
• end-to-end: real net.Socket against a locally-bound plain-TCP server, drives LOGIN -> SELECT -> IDLE, calls server.notify("mbx-1", 7) from outside the session, asserts client receives * 7 EXISTS
• end-to-end: client bound to a different mailbox does NOT receive the notification
• end-to-end: client that is authenticated and SELECT-ed but NOT in IDLE does NOT receive the notification

Documentation fixes

Three real errors surfaced while reading the docs I shipped in PR #76:

1. packages/imap-server/docs/quickstart.md -- "App passwords" section prescribed "store hashed (argon2) in your database". Contradicts the rewritten authentication contract: AuthAdapter is interface-only. Fixed.

2. packages/imap-server/docs/quickstart.md -- "IDLE" section said "call the server's notification mechanism" without naming one, because no API existed. Fixed -- shows the real server.notify() call.

3. packages/imap-server/docs/deployment.md -- Fly.io and Railway Dockerfiles used node --import tsx src/main.ts combined with pnpm install --prod. The --prod flag strips dev dependencies including tsx, which breaks runtime. Fixed -- multi-stage Dockerfile compiles TypeScript to dist/ in a build stage, runs node dist/main.js from a --prod runtime stage.

Verification

• pnpm --filter @rafters/mail-imap-server test: 10 passing
• pnpm --filter @rafters/mail-imap-server typecheck: clean
• pnpm --filter @rafters/mail-imap-server build: ESM + dts clean
• pnpm lint: 0 warnings, 0 errors
• oxfmt --check on all modified files: clean
• legion-simplify gate: clean

Stack

Chains off chore/package-readmes (#76), which chains off chore/imap-build-pipeline (#73). When #73 and #76 merge, this branch rebases cleanly onto main.

Note on PR #77

A parallel agent working on issue #57 (Spectrum TCP bridge) created PR #77 from the original feat/imap-server-notify branch with a mismatched title. This PR is the same notify work on a fresh branch (feat/imap-server-notify-api) with the correct title. PR #77 should be closed; Sean can handle that cleanup in the morning.

Why it matters

The @rafters/mail-imap-server package ships IMAP over Node TCP. IDLE push is a core IMAP feature (RFC 2177). Without notify(), a deployed Node IMAP server cannot wake IDLE clients when new mail arrives -- every client would sit in indefinite IDLE and see new mail only after timing out and re-selecting. A silent feature gap that would reach production if this package ships at 0.1.0 without the fix.