WRNexusJS/packages/plugin

@wrnexus/plugin

Least-privilege package permissions

Package manifests declare every framework capability they register:

{
  "wrnexus": {
    "permissions": ["routes", "migrations"],
    "routes": [{ "kind": "api", "path": "/api/example", "entry": "./route.ts" }]
  }
}

Applications can enable fail-closed grants:

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.