Repository navigation
docs(plugins): note that a missing hook capability fails silently - #4486
Conversation
The capability table says EmDash registers a gated hook only when the manifest declares the matching capability, but not what an author sees when it does not. The plugin installs and activates normally, its other hooks still run, and nothing appears in the admin interface, so the only symptom is a handler that never fires. The sole signal is a console.warn from registerPluginHook, and manifest validation does not cross-check hooks against capabilities. Hit this while moving four WordPress sites onto EmDash. Adds a caution aside with the exact log line so it is greppable. No behavior change.
|
|
All contributors have signed the CLA ✍️ ✅ |
github-actions
Bot
added
review/needs-review
![emdashbot[bot]](https://avatars.githubusercontent.com/in/3255304?s=60&v=4){kind=small}
There was a problem hiding this comment.
The approach is right: a short caution aside under the capability table, documenting what authors see when a gated hook's capability is missing. Both reviewers approved with no findings. The documented warning text matches the implementation in HookPipeline.registerPluginHook, and only the gated hook is skipped. Neither reviewer found a manifest, install or admin-UI check that surfaces the problem earlier. The aside also follows the page's docs conventions. Neither reviewer ran builds, linters or tests.
Reviewed by anthropic/claude-opus-5-5 and openai/gpt-6.1-sol.
|
I have read the CLA Document and I hereby sign the CLA. |
|
recheck |
emdashbot
Bot
added
review/needs-review
github-actions
Bot
added
review/approved
|
Thanks for contributing to EmDash! 🎉 Join the EmDash Discord, then run |
What does this PR do?
Documents what an author actually sees when a hook's required capability is missing from the manifest.
The capability table above says EmDash "registers them only when the manifest declares the matching capability", which is accurate but stops short of the consequence. In practice the plugin installs and activates normally, its other hooks keep running, and nothing appears in the admin interface. The only symptom is a handler that never fires, and the only signal is a
console.warnfromregisterPluginHookinpackages/core/src/plugins/hooks.ts. Manifest validation does not cross-check hooks against capabilities, so nothing catches it earlier.I hit this while moving four WordPress sites onto EmDash: a declared hook was silently dropped and the warning was in the Worker log. We now test that every declared hook's capability is also declared. This aside points authors at the log before they start debugging the handler.
Adds a caution aside with the exact log line so it is greppable. No behavior change.
Type of change
Your connection to this change
Checklist
pnpm typecheckpassespnpm lintpassespnpm testpasses (or targeted tests for my change)pnpm formathas been runOn the unchecked boxes, so a reviewer does not have to work out which apply:
typecheckandtestfilter to{./packages/**}and{./packages/*}, so neither coversdocs/. I ran the gate that does:pnpm --filter docs buildsucceeds, 95 pages, and the aside renders on the built page.oxlint --type-aware --deny-warnings docs/is clean.prettier --checkon the changed file is clean.docsisprivateand listed in.changeset/config.jsonignore.AI assistance disclosure
The aside wording and this description were drafted with Claude Opus 5 and reviewed with Claude Fable 5.1. I hit the problem myself during the migrations, verified the behavior against
main(theregisterPluginHookpath inhooks.ts, the absence of any cross-check inmanifest-schema.ts, and the existingcapability enforcementtests inpackages/core/tests/unit/plugins/hooks.test.ts), reviewed the complete diff, and ran the docs build and linters before opening this.Screenshots / test output
Not applicable — prose-only change to one page.