61 lines
2.3 KiB
Markdown
61 lines
2.3 KiB
Markdown
# @wrnexus/plugin
|
|
|
|
## Least-privilege package permissions
|
|
|
|
Package manifests declare every framework capability they register:
|
|
|
|
```json
|
|
{
|
|
"wrnexus": {
|
|
"permissions": ["routes", "migrations"],
|
|
"routes": [{ "kind": "api", "path": "/api/example", "entry": "./route.ts" }]
|
|
}
|
|
}
|
|
```
|
|
|
|
Applications can enable fail-closed grants:
|
|
|
|
```ts
|
|
export default {
|
|
pluginPermissions: {
|
|
enforce: true,
|
|
grants: { "example-plugin": ["routes"] },
|
|
},
|
|
};
|
|
```
|
|
|
|
Discovery rejects used-but-undeclared capabilities with
|
|
`WRN-PLUGIN-PERMISSION-UNDECLARED` and ungranted capabilities with
|
|
`WRN-PLUGIN-PERMISSION-DENIED`. Permissions cover components, browser runtime,
|
|
assets, styles, routes, middleware, migrations, config, transforms,
|
|
diagnostics/tooling, and server/build hooks.
|
|
|
|
## Compatibility matrices
|
|
|
|
Manifests can add `compatibility: { bunMin: "1.3.0", os: ["linux",
|
|
"darwin"] }` alongside `runtimes` and `requires`. Use
|
|
`testPluginCompatibility(manifest, targets)` in a package test to exercise the
|
|
complete support matrix. Runtime discovery enforces the same Bun minimum, OS,
|
|
runtime, and capability declarations used by the test kit.
|
|
|
|
Deterministic WRNexusJS plugin contracts for configuration, AST/code transforms,
|
|
diagnostics, development servers, production builds, and DevToolbar extensions.
|
|
|
|
Use `definePlugin()` and declare `enforce`, `before`, or `after` when ordering matters.
|
|
Duplicate names and dependency cycles are rejected.
|
|
|
|
## Complete lifecycle and contributions
|
|
|
|
Plugins may implement `setup`, `configure`, `configResolved`, `transformAst`,
|
|
`transformCode`, `diagnostics`, `routes`, `configureServer`, `buildStart`,
|
|
`buildEnd`, `render`, `deploy`, `shutdown`, and `hmrUpdate`. The runner preserves
|
|
resolved plugin order for every hook and executes `setup` exactly once.
|
|
|
|
In addition to components, routes, middleware, assets, styles, runtimes, and
|
|
migrations, plugins can contribute `directives`, `cliCommands`,
|
|
`virtualModules`, `deploymentAdapters`, `configSchemas`, `documentation`, and
|
|
`typeDefinitions`. Names are collision checked. Configuration schemas run after
|
|
configuration resolution, CLI commands are callable as normal `wrnexus`
|
|
commands, directives participate in AST transformation, and production builds
|
|
materialize virtual modules and invoke matching contributed adapters.
|