feat(plugin): expose dev server ready hook

[xusd320]

Summary

• Expose the actual adapter-reported client dev origin to plugins without wrapping or replacing the selected bundler adapter.
• Notify plugins once for each active immutable development Session.
• Keep plugin CLI shortcuts responsive and isolated while ready hooks or stale Session contributions are pending.

Changes

• Add the public DevServerReadyContext and PluginHooks.devServerReady() lifecycle API with origin and a Session-scoped AbortSignal.
• Activate ready hooks only after the Supervisor installs the Session and monitors controller.done; shutdown and controller failure abort pending hook work before disposal.
• Replay the hook on Session replacement, while ordinary bundler/HMR rebuilds and semantic no-ops do not trigger it again.
• Bind CLI shortcuts independently from ready-hook completion and collect contributions per Session, so a stale pending contribution cannot block or rebind over its replacement.
• Preserve the existing independent timing of listener readiness and initial beforeBuild() / afterBuild(), and document that no ordering is guaranteed.
• Document cooperative cancellation: close and replacement abort the signal and wait for in-flight ready work to settle before disposal.
• Add lifecycle, Session, Supervisor cleanup/replacement/concurrency, validation, type-contract, and bilingual documentation coverage.

Validation

• npm run check-types
• npm run lint
• npm test
• npm --workspace evjs-docs run build
• git diff --check

Risk / rollout

• Additive plugin API; existing plugins and bundler adapters are unchanged.
• Development-only behavior; production build paths do not invoke the hook.
• Plugins adopting the hook must require an EVJS version that includes it.
• A ready hook that rejects while its Session is active fail-stops the development run and runs normal controller cleanup and reverse-order plugin disposal.
• Cancellation is cooperative; a hook that ignores signal can delay Session replacement or shutdown.

Reviewer notes

• Please focus on Supervisor activation/teardown ordering, Session ownership of asynchronous shortcut contributions, and the explicit lack of ordering between listener readiness and the first output cycle.
• After this lands, facade integrations can remove adapter proxies, _internal/build imports, and bundler config recomposition used only to discover the actual origin.

Summary by CodeRabbit

• New Features

  • Added the devServerReady() plugin lifecycle hook.
  • Plugins can receive the development server’s actual origin after the client listener starts.
  • Hooks support cooperative cancellation and run once per development session.
  • Development session shutdown and replacement now safely handle pending readiness hooks and failures.

• Documentation

  • Added lifecycle diagrams, API reference details, usage examples, and localized documentation for the new hook and context.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fd010e9a-1dca-437a-8a9c-6f79a099f9b4

📥 Commits

Reviewing files that changed from the base of the PR and between 93d308d and 5bb0c25.

📒 Files selected for processing (16)

• CHANGELOG.md
• docs/docs/plugin-authoring.md
• docs/docs/plugin-hooks.md
• docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/plugin-authoring.md
• docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/plugin-hooks.md
• packages/ev/src/_internal/build/dev-session.ts
• packages/ev/src/_internal/build/dev-supervisor.ts
• packages/ev/src/_internal/build/plugin-lifecycle.ts
• packages/ev/src/plugin/hook-names.ts
• packages/ev/src/plugin/index.ts
• packages/ev/tests/commands.test.ts
• packages/ev/tests/config.test.ts
• packages/ev/tests/dev-session.test.ts
• packages/ev/tests/dev-supervisor.test.ts
• packages/ev/tests/plugin-lifecycle.test.ts
• packages/ev/tests/plugin-settings.test.ts

---

📝 Walkthrough

Walkthrough

The PR adds devServerReady({ origin, signal }) to the plugin lifecycle. Development sessions activate the hook once, pass the actual client origin, await shutdown, abort pending work, and coordinate session replacement with CLI shortcut ownership.

Changes

Development server readiness

Layer / File(s)	Summary
Readiness hook contract and runner packages/ev/src/plugin/index.ts, packages/ev/src/plugin/hook-names.ts, packages/ev/src/_internal/build/plugin-lifecycle.ts, packages/ev/tests/plugin-lifecycle.test.ts, packages/ev/tests/plugin-settings.test.ts, packages/ev/tests/config.test.ts	Adds DevServerReadyContext, the optional devServerReady hook, hook registration, sequential execution, cancellation, context validation, and setup-only enforcement.
Session activation and shutdown packages/ev/src/_internal/build/dev-session.ts, packages/ev/tests/dev-session.test.ts, packages/ev/tests/commands.test.ts	Activates readiness hooks once per session with the controller origin. Shutdown aborts and awaits pending hooks before closure and disposal.
Supervisor activation and shortcut ownership packages/ev/src/_internal/build/dev-supervisor.ts, packages/ev/tests/dev-supervisor.test.ts	Transfers shortcut ownership during session replacement, prevents stale bindings, and reports readiness failures through the active supervisor.
Lifecycle documentation and release notes CHANGELOG.md, docs/docs/plugin-authoring.md, docs/docs/plugin-hooks.md, docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/*	Documents the hook lifecycle, origin, cancellation, failure, disposal, context restrictions, and shortcut behavior in English and Chinese.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DevSupervisor
  participant DevSession
  participant Plugin
  participant CLIShortcuts
  DevSupervisor->>DevSession: activate current development session
  DevSession->>Plugin: call devServerReady with origin and signal
  Plugin-->>DevSession: complete or reject
  DevSupervisor->>CLIShortcuts: bind shortcuts for current session
  DevSupervisor->>DevSession: close or replace session
  DevSession->>Plugin: abort pending hook and await settlement

Loading

Possibly related PRs

• afx-team/evjs#86: Introduced the development-session and CLI shortcut lifecycle extended by this PR.
• afx-team/evjs#87: Introduced the immutable session lifecycle extended with readiness activation.

Suggested reviewers: hongxuwei

✨ 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 xusd320/dev-server-ready-hook

---

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