Improve package app error responses

[kentcdodds]

Summary

• Replace generic package app 500 bodies with safe, actionable HTML or JSON responses.
• Distinguish Kody host setup/realtime failures from package entrypoint crashes.
• Keep stack traces/internal error details out of user-facing responses while pointing package owners to runtime debug runs.
• Reuse the shared wantsJson helper and add coverage for HTML, JSON, and package-entrypoint failure messaging.

Validation

• PR checks are green after rebasing on latest main: Validate, preview deploy, CodeRabbit, and Cursor Bugbot.
• Pre-push typecheck, unit tests, and E2E passed while pushing the branch.

  

Summary by CodeRabbit

• Bug Fixes

  • Improved error responses when package apps fail: HTML for browser requests and structured JSON for API calls.
  • Responses now include contextual package metadata, clearer titles/summaries, and actionable debug guidance.
  • Failure cases (host setup, realtime connect, entrypoint crash) report distinct, user-facing messages.

• Tests

  • Updated tests to assert richer HTML and JSON 500 responses and enhanced crash/debug messaging.

[coderabbitai]

📝 Walkthrough

Walkthrough

The package app request handler replaces generic "Internal Server Error" responses with contextual error information. A new failure categorization system (PackageAppFailureKind) distinguishes host-setup, realtime-connect, and package-entrypoint failures. Error responses are content-negotiated: JSON when Accept includes application/json, otherwise styled HTML. Tests verify both response formats include metadata and failure-specific guidance.

Changes

Package App Error Response Enhancement

Layer / File(s)	Summary
Imports and HTML Utilities packages/worker/src/app/handlers/package-app.ts	Remix HTML utilities (html, createHtmlResponse) and wantsJson(request) are imported for content-negotiated error responses.
Error Response Infrastructure packages/worker/src/app/handlers/package-app.ts	PackageAppFailureKind and createPackageAppErrorResponse(...) map failure kinds to title/summary/next_step and return either JSON or styled HTML 500 responses including package id/name and request path.
Error Path Integration packages/worker/src/app/handlers/package-app.ts	Realtime connection, host-setup/load-and-build, and package entrypoint error handlers now call createPackageAppErrorResponse(...) with the appropriate failure kind instead of returning a generic 500.
Tests and Assertions packages/worker/src/app/handlers/package-app.node.test.ts	Tests assert HTML 500 with explanatory text for normal requests, structured JSON 500 when accepting JSON with error/details/next_step and package metadata/path, and updated crash-path assertions including debug messaging.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• kentcdodds/kody#424: Modifies the same package-app handler and error paths, including reportPackageAppFailure() calls and host-setup/realtime/entrypoint error handling changes.

Poem

A rabbit hops through error trails,
With JSON and HTML, no dry "Internal" wails,
It bundles names, paths, and helpful cues,
So crashes tell their story, not confuse,
Debug carrots and cozy error tales. 🐰

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: improving package app error responses, which is reflected in both modified files that replace generic 500 errors with structured HTML/JSON responses.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/package-app-error-pages-b855

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔎 Preview deployed: https://kody-pr-426.kentcdodds.workers.dev

Worker: kody-pr-426
D1: kody-pr-426-db
KV: kody-pr-426-oauth-kv

Mocks:

• cloudflare: https://kody-pr-426-mock-cloudflare.kentcdodds.workers.dev/__mocks (kody-pr-426-mock-cloudflare)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7ba8d73. Configure here.}