fix: gracefulShutdown awaits async cleanup after server.close drain (v0.0.4)

[y1o1]

Summary

• Cleanup callback now runs inside the server.close() callback (after in-flight requests drain) and is awaited, instead of the previous synchronous fire-before-close shape that silently dropped any returned Promise.
• cleanup parameter type widens from () => void to () => void | Promise<void> — structurally backward-compatible.
• Cleanup errors are caught and logged via console.error("gracefulShutdown: cleanup error", err); process.exit(0) still runs.
• server.closeAllConnections() invoked alongside server.close() to drain keep-alive sockets (Node.js >= 18.2.0).

Spec: auth/.claude/superpowers/specs/2026-05-05-d5-builder-context-lifecycle.md — cross-repo gracefulShutdown semantics fix section.

This release (v0.0.4) is a publish prerequisite for o3co/auth.provider v0.5.2 — the templates/standalone/src/app.mts:117 call gracefulShutdown(server, () => handle.dispose()) was already passing an async dispose() that the previous sync impl silently dropped. With this fix, the lifecycle drain in auth.provider v0.5.x is properly awaited before the process exits.

TDD evidence

• 4 new RED tests (all failed against current sync impl, all pass against new impl):
  • invokes cleanup inside server.close callback (after in-flight requests drain) — verifies call order ["close", "cleanup", "exit"]
  • awaits an async cleanup before exiting — verifies process.exit only fires after cleanup's Promise resolves
  • logs cleanup errors via console.error and still exits — verifies error path is caught + logged
  • calls server.closeAllConnections to drain keepalive sockets
• 2 existing tests updated (async + closeAllConnections mock + microtask flush) to keep working under the new ordering.

Test plan

• pnpm test — all 27 tests pass (5 test files)
• pnpm typecheck — 0 errors
• pnpm build — clean
• pnpm lint — clean (after biome --write formatting pass)

Migration

The signature widening is structurally backward-compatible — every previous cleanup: () => void shape still satisfies () => void | Promise<void>. No code change required at call sites unless callers want to take advantage of awaited async cleanup. Behavior change: cleanup now runs after request drain and is awaited; fire-and-forget ordering is gone.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the gracefulShutdown utility to run cleanup only after server.close() completes, await async cleanup, and add keep-alive connection draining behavior; it also expands test coverage and documents the behavior change for the upcoming v0.0.4 release.

Changes:

• Run cleanup inside the server.close() callback and await it (with error logging) before calling process.exit(0).
• Invoke server.closeAllConnections() during shutdown to address lingering keep-alive sockets.
• Add/adjust Vitest coverage for ordering, async cleanup awaiting, error logging, and closeAllConnections() usage; add a v0.0.4 changelog entry.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
src/shutdown.mts	Moves cleanup into the server.close() callback, awaits it, logs cleanup errors, and calls closeAllConnections().
src/tests/shutdown.test.mts	Adds new tests for shutdown ordering/awaiting/error logging and updates existing tests to account for the new ordering and closeAllConnections().
CHANGELOG.md	Documents the v0.0.4 behavior change, including awaited cleanup and keep-alive draining.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.