[kentcdodds]

Intent

Document the improved kody dev (from the @kodycodes/cli changes) in the package guides that agents read.

Door: two-way

Cleanup: none

Why

kody dev now has zero-downtime rebuilds, real error pages and logs, live reload, an agent mode (--json, /__kody/dev/status, attach), stable ports, local kody.app.client / kody.app.assets serving, and a kody.dev.prebuild hook. The guides only said "serves on localhost with hot reload", so agents can't discover any of this.

Local bundling also now treats bare Node builtins (stream, fs/promises, …) the way publish does. Server-side rendering with a package's Node build still fails at request time in an ES module Worker, so the guide says to use the Workers/edge entry. The @kentcdodds/package-app-kit TanStack starter hits exactly this case.

Summary

• docs/guides/package-apps.md, section "Local testing with kody dev":
  • what kody dev does while it runs (rebuilds, error pages, logs, live reload, /_assets parity, ports);
  • the local-only package.json#kody.dev block (prebuild, ignore) with an example;
  • how agents drive it (kody dev fetch attach, --json, --ready-file, the status endpoint).
• docs/guides/package-apps.md, "Fetch handlers": the entry runs with nodejs_compat, so builtins stay external in publish and dev. A CommonJS require() of a builtin throws "Dynamic require of … is not supported". Import the Workers/edge entry instead, for example react-dom/server.edge for renderToReadableStream.
• docs/guides/package-lifecycle.md: the Apps row of the local CLI testing table mentions --json for agents.

Referenced issues and PRs

Unblocked: the kody dev CLI changes in kody-bot/cli PRs #58–#69 are merged and released in @kodycodes/cli@1.26.2 (tag v1.26.2 = merge of #69). Docs event list and behavior match that release (including later polish in #64–#69: package-graph sizing is internal; JSON event types unchanged; dev fetch --json still emits build_error).

Testing

• oxfmt ran in the pre-commit hook; node tools/check-docs-no-hosted-execute.ts passes.
• The edited sections stay far below the 24,000-character guide section budget.
• Every behavior described is covered by the CLI tests and was checked against the published CLI help / dev-events types in @kodycodes/cli@1.26.2. For the edge-entry note, a minimal app on react-dom/server returned 500 with "Dynamic require of "util"", and the same app on react-dom/server.edge returned 200.
• Rebased onto latest main before marking ready.

  

---

Note

Low Risk
Documentation-only updates to package guides; no runtime, auth, or application code changes.

^{Reviewed by Cursor Bugbot for commit beb33bf. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Expanded the kody dev guide with details on rebuild requests, development errors, request-tagged console output, HTML live reload, local asset URLs, port selection, and development settings.
  • Added guidance for starting kody dev fetch, its JSON readiness and event output, and the status endpoint.
  • Clarified fetch-handler compatibility with Node built-ins, including that CommonJS require() calls for built-ins fail at request time and that dependencies targeting Node builds should use Workers or edge entries.
  • Updated local-testing instructions to include --json output.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 8e54d18e-b0c9-4e02-a15f-7c2082f9c319

📥 Commits

Reviewing files that changed from the base of the PR and between c2d1c12 and beb33bf.

📒 Files selected for processing: 2

• docs/guides/package-apps.md
• docs/guides/package-lifecycle.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

📝 Walkthrough

The Apps guides now describe kody dev behavior and settings, kody dev fetch startup and readiness options, and Node builtin behavior in fetch entries.

Changes: Apps guide updates

Layer / File(s)	Summary
Document local development behavior docs/guides/package-apps.md	Documents rebuild handling, development error pages, request-tagged console output, reload behavior, asset URLs, stable port selection, and kody.dev settings.
Document CLI testing and readiness docs/guides/package-apps.md, docs/guides/package-lifecycle.md	Describes how kody dev fetch attaches to a running server or starts a one-shot server. Documents JSON lifecycle events, readiness files, status information, and the --json option for agent use.
Document fetch-entry runtime constraints docs/guides/package-apps.md	Explains that nodejs_compat leaves Node built-ins external, that CommonJS require() of a builtin fails at request time, and that Node-build dependencies should use Workers or edge entries.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to beb33

This change documents local development and agent-oriented fetch behavior; no specific user-facing regression is evidenced, so merge risk is minimal.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title clearly identifies the documentation update and its main topics: kody dev behavior, kody.dev settings, and agent mode. It is concise and relevant, although it does not mention the fetch-hand…
Description check		The description follows the required template and includes Intent, Why, Summary, Referenced issues and PRs, and Testing sections. It provides clear scope, rationale, implementation details, and valida…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[cursor]

Unblocked and ready to ship

Verified before marking ready:

1. CLI release includes the documented work. @kodycodes/cli@1.26.2 (npm + GitHub release v1.26.2, published 2026-10-15) is tagged at the merge commit of fix(dev): absorb late watcher echoes after a failed prebuild kody-bot/cli#69. Compare confirms PRs fix: prepare worker env in deploy workflow #58–Add commit-time quality checks #69 are all ancestors of that tag (no pending/failed release needed).

2. Docs match shipped behavior. Cross-checked the guide against 1.26.2 help text and dev-events types:

   • NDJSON events remain ready, rebuild_start, rebuild_ok, build_error, runtime_error, log (feat: add secret-aware fetch gateway #61; Adopt suffix-based Vitest test routing #67 still emits build_error for dev fetch --json on one-shot failures — already covered by the listed event set).
   • #64/#65 package-graph sizing / clearer size-limit errors are internal CLI improvements; no guide wording change required.
   • #68/#69 overlay CSS / prebuild watcher polish do not change documented agent-facing APIs.
   • nodejs_compat / edge-entry note still matches shipped bundling.

3. Branch hygiene. Rebased onto latest main (clean), force-pushed, marked ready for review.

Following ship-pr from here (CI + Bugbot → merge).

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[github-actions]

🔎 Preview deployed: https://kody-pr-3829.kody-a99.workers.dev

Worker: kody-pr-3829
Platform worker: kody-pr-3829-platform (https://kody-pr-3829-platform.kody-a99.workers.dev)
Runtime worker: kody-pr-3829-runtime (https://kody-pr-3829-runtime.kody-a99.workers.dev)
API worker: kody-pr-3829-api (https://kody-pr-3829-api.kody-a99.workers.dev)
D1: kody-pr-3829-db
KV: kody-pr-3829-oauth-kv

Seed login (public preview fixture)

• Email: me@kentcdodds.com
• Password: ilikecode
• Username: user-me

Prefer MCP/API/control-kody execute for proof. Browser only when UI is under test.

• Deep link (UI login still needed): Sign in → /account — change redirectTo to the path under test (for example /@user-me/your-pkg).
• Already signed in (reuse CLI cookie): npm run control-kody -- browse --origin https://kody-pr-3829.kody-a99.workers.dev --path /account

Do not post session cookies or tokens in PR comments.

Mocks:

• cloudflare: https://kody-pr-3829-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-3829-mock-cloudflare)