ldap-rest 1.2.1 → 1.3.0

package/docs/plugin-development/README.md

@@ -8,6 +8,7 @@ This guide will help you create powerful, production-ready plugins for LDAP-Rest
 - [Plugin Structure](#plugin-structure)
 - [Creating Your Plugin](#creating-your-plugin)
 - [Custom Configuration Options](#custom-configuration-options)
+  - [Plugin options](./options.md)
 - [Loading Your Plugin](#loading-your-plugin)
 - [Plugin Features](#plugin-features)
 - [Configuration Best Practices](#configuration-best-practices)
@@ -59,8 +60,11 @@ export default class MyPlugin extends DmPlugin {
 
 - **this.server**: DM server instance
 - **this.config**: Complete configuration object
+- **this.options(declarations)**: Values of the options the plugin declares,
+  typed and checked, see [plugin options](options.md)
 - **this.logger**: Winston logger instance
-- **this.registeredHooks**: Access to global hook registry
+- **this.hookBus**: The server's hooks: chain, notify and wait on them, see
+  [hooks](hooks.md#the-bus)
 - **this.fetch**: `fetch` timed into the
   [outbound metrics](../usage/operations.md#metrics) under the plugin's
   name; the lint refuses a bare `fetch` or `node-fetch` under `src`, and a
@@ -272,99 +276,15 @@ npx ldap-rest
 
 ## Custom Configuration Options
 
-LDAP-Rest automatically accepts and stores any unknown command-line options in the config object. This allows your plugin to define custom configuration without modifying core files.
+A core plugin declares its options next to its code, in a
+`<plugin>.options.ts` file, and reads them through `this.options()` with their
+types, defaults and checks. See [plugin options](options.md).
 
-### How It Works
-
-1. **Command-line option format**: `--option-name value`
-2. **Converted to config key**: `option_name` (dashes become underscores)
-3. **Environment variable format**: `DM_OPTION_NAME` (uppercase with underscores)
-4. **Access in plugin**: `this.config.option_name`
-
-### Single Value Options
-
-```bash
-# Command line
-npx ldap-rest \
-  --webhook-url https://example.com/webhook \
-  --webhook-timeout 5000 \
-  --webhook-retry true
-
-# Environment variables
-export DM_WEBHOOK_URL=https://example.com/webhook
-export DM_WEBHOOK_TIMEOUT=5000
-export DM_WEBHOOK_RETRY=true
-```
-
-In your plugin:
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Access custom options (converted to snake_case)
-  const url = this.config.webhook_url;        // string
-  const timeout = this.config.webhook_timeout; // string (convert if needed)
-  const retry = this.config.webhook_retry;     // string 'true' (convert if needed)
-
-  // Type conversion
-  const timeoutNum = parseInt(timeout as string || '3000');
-  const retryBool = (retry as string) === 'true';
-}
-```
-
-### Multiple Value Options
-
-Repeat the same option multiple times to create an array:
-
-```bash
-# Command line
-npx ldap-rest \
-  --allowed-domain example.com \
-  --allowed-domain test.com \
-  --allowed-domain dev.com
-
-# Environment variable (comma or semicolon separated)
-export DM_ALLOWED_DOMAINS=example.com,test.com,dev.com
-```
-
-In your plugin:
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Access as array (note: singular becomes plural in config key)
-  const domains = this.config.allowed_domain as string[];
-  // or sometimes stored as: this.config.allowed_domains
-
-  this.logger.info(`Allowed domains: ${domains.join(', ')}`);
-}
-```
-
-### Configuration Priority
-
-Values are resolved in this order (later overrides earlier):
-
-1. **Default value** in your plugin
-2. **Environment variable** (`DM_OPTION_NAME`)
-3. **Command-line argument** (`--option-name`)
-
-```typescript
-constructor(server: DM) {
-  super(server);
-
-  // Provide defaults for optional configuration
-  const webhookUrl = this.config.webhook_url || 'http://localhost:8080/webhook';
-  const webhookTimeout = parseInt(this.config.webhook_timeout as string || '3000');
-  const maxRetries = parseInt(this.config.max_retries as string || '3');
-
-  // Validate required configuration
-  if (!this.config.webhook_secret) {
-    throw new Error('--webhook-secret is required for authentication');
-  }
-}
-```
+A plugin outside the repository cannot add to `src/config/args.ts` yet. It keeps
+reading `this.config.<name>`: LDAP-Rest accepts and stores unknown
+`--option-name value` pairs under `option_name`, with `--option-name` and
+`DM_OPTION_NAME` overriding in that order. See
+[configuration](../usage/configuration.md#environment-variables).
 
 ---
 
@@ -684,7 +604,15 @@ hooks: Hooks = {
 
 ### Exposing API Endpoints
 
-Create REST API endpoints for your plugin. **Important:** Always use the `asyncHandler` wrapper for async routes to ensure errors are properly handled and don't crash the server.
+Declare routes with [`defineRoute`](routes.md): it types and validates the
+request (`params`, `query`, `body`), answers a failing request with a 400
+naming the paths at fault, and records the route for the OpenAPI document.
+The `asyncHandler` form below remains for routes that have not been migrated
+yet.
+
+Create REST API endpoints for your plugin. Always use the `asyncHandler`
+wrapper for async routes, so that errors are properly handled and do not
+crash the server.
 
 ```typescript
 import DmPlugin, { asyncHandler } from '../../abstract/plugin';
@@ -791,6 +719,29 @@ app.get(
 );
 ```
 
+**Wrapping an error keeps its answer:**
+
+Wrap with `cause` rather than in the message alone. The status and the class
+of what was thrown are read through the chain, so a refusal stays a 403 and
+a timeout a 504 wherever it surfaces:
+
+```typescript
+// ✅ GOOD: the refusal keeps its 403 when it reaches the client
+throw new Error(`Failed to add group ${dn}: ${String(err)}`, { cause: err });
+
+// ❌ BAD: a 403 becomes a 500, and its message is all that is left
+throw new Error(`Failed to add group ${dn}: ${String(err)}`);
+```
+
+**Refusing a caller:**
+
+An authorization plugin throws `AuthzRefusedError`, whose message is for the
+operator: it names the model and the branch it judged. The client is told
+`AUTHZ_REFUSED` with `code: "forbidden"` instead, whatever a plugin wrapped
+it in on the way. A refusal that is not an authorization plugin's is any
+`ForbiddenError`, answered with its own message; `isAuthzRefusal(err)` tells
+the two apart.
+
 **Custom error handling:**
 
 ```typescript

package/docs/plugin-development/dependencies.md

@@ -27,7 +27,7 @@ overrides builds a second instance, and it needs a name of its own.
 ### Hook Dependencies
 
 **Hook Providers**: Plugins that implement hooks (via `hooks: Hooks = { ... }`)
-**Hook Consumers**: Plugins that call hooks (via `runHook()` or `launchHooks()`)
+**Hook Consumers**: Plugins that raise hooks (via `this.hookBus`)
 
 ## Complete Dependency Graph
 
@@ -601,10 +601,10 @@ refused before a plugin judges its content, or replaces it.
 2. Returns modified data to next plugin
 3. Last plugin's return value is used
 
-For non-chained hooks:
+For notified hooks, see [hooks](hooks.md#the-bus):
 
-- All hooks execute in parallel
-- Order doesn't matter
+- All hooks run one after the other, in load order
+- A failing one is logged and the next still runs
 
 **Example**: `ldapdeleterequest` chain
 
@@ -642,11 +642,16 @@ export default class MyPlugin extends DmPlugin {
 
 ### Providing Hooks
 
+A hook is declared in `src/hooks.ts` before anything raises it, and raised
+through the bus of the kind it is, see [hooks](hooks.md#the-bus):
+
 ```typescript
 export default class MyPlugin extends DmPlugin {
   async someMethod() {
-    // Fire a hook for other plugins to consume
-    await this.server.launchHooks('myCustomHook', [param1, param2]);
+    // Thread a value through the subscribers of a chained hook
+    value = await this.hookBus.chain('ldapsearchopts', value);
+    // Tell the subscribers of a notified one, without waiting for them
+    this.hookBus.notify('ldapadddone', dn, entry, changeContext(req));
   }
 }
 ```

package/docs/plugin-development/hooks.md

@@ -1,34 +1,143 @@
 # Core hooks
 
-The hooks a plugin can register. Their arguments and return values are
-those typed in [hooks.ts](../../src/hooks.ts), which is the reference.
+Hooks are how plugins talk to each other. Each one is declared in
+[hooks.ts](../../src/hooks.ts), which is the reference for the arguments it
+gets and what it must answer; a plugin subscribing to a hook it does not
+name there does not compile.
 
-## Demo hooks
+## The bus
 
-- **hello**: called by [helloworld demo plugin](../../src/plugins/demo/helloworld.ts)
+`this.hookBus` (or `server.hookBus`) is how a plugin raises a hook, and how a
+test waits for one. It has one method per kind of hook, told apart by what a
+subscriber answers:
 
-## [LDAP](../../src/lib/ldapActions.ts) hooks
+| Kind     | Method                                                | Subscriber                                                                                 |
+| -------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| chained  | `chain(name, value)`                                  | answers the value, changed or not                                                          |
+| notified | `notify(name, ...args)`                               | answers nothing, not awaited                                                               |
+| notified | `notifyAndWait(name, ...args)`                        | answered nothing, awaited                                                                  |
+| notified | `notifyStrict(name, ...args)`                         | as `notifyAndWait`, but a failure goes to the caller                                       |
+| any      | `has(name)`, `subscribers(name)`                      | —                                                                                          |
+| any      | `settled()`                                           | resolves once every notification so far has run                                            |
+| any      | `set`, `subscribe`, `insert`, `unsubscribe`, `toLast` | add a subscriber, or move one: for a test, or for a plugin changing what its base declares |
 
-- **ldapsearchopts**: called before any ldapsearch to modify search options
-- **ldapsearchresult**: called after any ldapsearch to modify search result
-- **ldapaddrequest**: called before any ldapadd
-- **ldapadddone**: launched once an ldapadd has written the entry, not awaited
-- **ldapaddafter**: awaited once an ldapadd has written the entry, before it
-  answers, see [below](#ldapaddafter)
-- **ldapmodifyrequest**: called before any ldapmodify
-- **ldapdeleterequest**: called before any ldapdelete
-- **ldaprenamerequest**: called before any ldap rename/modifyDN operation
-- **ldapmodifyend**, **ldapdeleteend**, **ldaprenameend**: launched once a
-  modify, delete or rename is over, whatever became of it, see
-  [below](#ldapmodifyend-ldapdeleteend-ldaprenameend)
+A chained hook is handed its arguments as one value, a tuple when it has
+several. A notified hook is handed them one by one: its subscriber is
+`(dn, entry, context) => …`, never `([dn, entry], context) => …` — that form
+still compiles, the parameters being bivariant, but then reads the DN's first
+character as the DN.
+
+- **Chained.** The value goes from one subscriber to the next, each getting
+  what the one before answered; the last answer is the result. A subscriber
+  that throws stops the chain and the error travels up: a refusal is a
+  refusal. Several values are passed as one tuple.
+- **Notified.** Subscribers run one after the other, outside the request
+  that caused the write, and are told what happened and was judged: they
+  react as the server — synchronizing, publishing, keeping invariants —
+  whoever asked. `notify` does not wait for them and never fails: the write
+  they react to is done, and a failing subscriber is logged, with its plugin
+  and hook, and counted in the [hook failure
+  metrics](../usage/operations.md#metrics), then the next one still runs.
+- **`notifyStrict`** is for the rare subscriber whose failure is part of the
+  answer: a logout token reaches the provider only once what it closes is
+  recorded, so the library answers 400 and the provider retries. Every
+  subscriber runs even when one fails, and the first failure is raised once
+  they all have.
+
+A test that would otherwise sleep waits instead:
+
+```ts
+// One hook's subscribers
+await server.hookBus.notifyAndWait('ldapadddone', dn, entry, {});
+// or whatever the write under test started
+await server.hookBus.settled();
+```
+
+## Hooks
+
+<!-- hooks: generated from src/hooks.ts, do not edit by hand -->
+
+- **hello**: raised by the [demo plugin](../../src/plugins/demo/helloworld.ts) for `/hello`, answered by the demo plugins
+- **ldapsearchopts**: chained before any search, with its options
+- **ldapsearchrequest**: chained before any search, with `[base, options, request]`; an authorization plugin refuses by throwing
+- **ldapsearchresult**: chained after any search, with its result, before it is cached
+- **ldapsearchfilter**: chained on the result of a search after the cache, once per page, with `[result, request, options]`, to drop what the caller may not see
+- **ldapaddrequest**: chained before any add, with `[dn, entry, request]`
+- **ldapadddone**: notified once an add has written the entry, with the DN, the entry and the context, one by one; not awaited
+- **ldapaddafter**: notified once an add has written the entry, before it answers, with the DN, the entry and the context, one by one, see [below](#ldapaddafter)
+- **ldapmodifyrequest**: chained before any modify, with `[dn, changes, op, request]`
+- **ldapmodifydone**: notified once a modify is written, with the DN, the changes, the operation number and the context, one by one
+- **ldapmodifyend**: notified once a modify is over, whatever became of it, and its done subscribers have returned
+- **ldapdeleterequest**: chained before any delete, with `[dn, request]`
+- **ldapdeletedone**: notified once a delete is written, with the DN and the context, one by one
+- **ldapdeleteend**: notified once a delete is over, whatever became of it, and its done subscribers have returned
+- **ldaprenamerequest**: chained before any rename or move, with `[dn, newDn, request]`
+- **ldaprenamedone**: notified once a rename or a move is written, with the DN, its new DN and the context, one by one
+- **ldaprenameend**: notified once a rename is over, whatever became of it, and its done subscribers have returned
+- **oidcsessionvalid**: chained with the claims of a session and the verdict so far, see [the OpenID Connect page](../usage/plugins/auth/openid-connect.md)
+- **oidclogouttoken**: notified with the claims of a session a logout token or `/logout` ends
+- **oidclogin**: notified with the claims of a session just established
+- **ldapgroupvalidatenew**: chained before a group is created, with `[dn, entry]`
+- **ldapgroupadd**: chained before a group is added, with `[dn, entry]`
+- **ldapgroupadddone**: notified once a group is added, with the DN and the entry, one by one
+- **ldapgroupvalidatechanges**: chained before a group is modified, with `[dn, changes]`
+- **ldapgroupmodify**: chained before a group is modified, with `[dn, changes, op]`
+- **ldapgroupmodifydone**: notified once a group is modified, with the DN, the changes and the operation number, one by one
+- **ldapgrouprename**: chained before a group is renamed, with `[dn, newDn]`
+- **ldapgrouprenamedone**: notified once a group is renamed, with the DN and its new DN, one by one
+- **ldapgroupdelete**: chained before a group is deleted, with its DN
+- **ldapgroupdeletedone**: notified once a group is deleted, with its DN
+- **ldapgroupaddmember**: chained before members are added, with `[cn, members]`
+- **ldapgroupdeletemember**: chained before a member is removed, with `[cn, member]`
+- **ldapgroupvalidatemembers**: chained before a member is added, to judge the members, with `[dn, members]`
+- **\_ldapgrouplist**: chained around the list of groups, internal to the groups plugin
+- **onLdapEntryChange**: notified with the entry before and after any write, and who made it
+- **onLdapChange**: notified with the attributes a write changed
+- **onLdapMailChange**: notified with the mail before and after a change, or with no new mail for a delete
+- **onLdapAliasChange**: notified with the mail and the aliases before and after a change
+- **onLdapQuotaChange**: notified with the mail and the quota before and after a change
+- **onLdapForwardChange**: notified with the mail and the forwards before and after a change
+- **onLdapDisplayNameChange**: notified with the name before and after a change
+- **onLdapDriveQuotaChange**: notified with the drive quota before and after a change
+- **externaluserentry**: chained before an external member is created, with `[dn, entry]`
+- **externaluseradded**: notified once an external member is created, with the DN and the entry, one by one
+- **beforeAuth**: chained on a request before it is authenticated, with `[request, response]`
+- **afterAuth**: chained on a request once it is authenticated, with `[request, response]`
+- **getOrganisationTop**: chained before the top organization is answered, with `[request, entry]`
+- **scimusercreate**: chained before a SCIM user is created, with `[user, request]`
+- **scimusercreatedone**: notified once a SCIM user is created
+- **scimuserupdate**: chained before a SCIM user is replaced, with `[id, user, request]`
+- **scimuserupdatedone**: notified once a SCIM user is replaced, with id, user (one by one)
+- **scimuserdelete**: chained before a SCIM user is deleted, with `[id, request]`
+- **scimuserdeletedone**: notified once a SCIM user is deleted, with its id
+- **scimgroupcreate**: chained before a SCIM group is created, with `[group, request, base]`
+- **scimgroupcreatedone**: notified once a SCIM group is created
+- **scimgroupupdate**: chained before a SCIM group is replaced, with `[id, group, request]`
+- **scimgroupupdatedone**: notified once a SCIM group is replaced, with id, group (one by one)
+- **scimgroupdelete**: chained before a SCIM group is deleted, with `[id, request]`
+- **scimgroupdeletedone**: notified once a SCIM group is deleted, with its id
+- **scimbulkdone**: notified once a SCIM bulk request is answered
+- **twakedeletionreplay**: notified with the DN, the entry and the context, one by one when a delete asks of an entry that is already a tombstone
+<!-- /hooks -->
+
+## Flat entities
+
+A plugin built on `LdapFlat` (`--ldap-flat-schema`) raises one set of hooks
+per entity: `ldap${entity.name}` followed by the suffix of the shared hook of
+the same kind — `add` and `adddone`, `modify` and `modifydone`, `rename` and
+`renamedone`, `delete` and `deletedone`, with the same arguments — plus
+`{prefix}move` before an entry is moved, followed by `onLdapChange` as a
+modify is. A plugin watching one declares it beside its other hooks.
+
+## LDAP write hooks
 
 ### ldapaddafter
 
 For what must follow an add within the same request, such as provisioning
 the account the entry describes.
 
-- Subscribers get `[dn, entry]` and the change context, as `ldapadddone`
-  does. They run one after the other, and `add()` answers once the last has
+- Subscribers get the DN, the entry and the change context, one by one, as
+  `ldapadddone` does. They run one after the other, and `add()` answers once the last has
   returned.
 - An error is logged and goes no further: the add has succeeded, and the
   next subscriber still runs. A subscriber that can fail owns its repair
@@ -38,7 +147,8 @@ the account the entry describes.
   empty. Some of these follow an API call all the same, so select entries by
   their DN or attributes rather than by an empty context.
 - The entry is the one submitted, after `ldapaddrequest`, not what the
-  directory holds: no operational attributes, and the password as given.
+  directory holds: no operational attributes, and a `Buffer` value — a
+  password sent that way — read as a string.
 - `ldapadddone` and `onLdapEntryChange` fire whatever this hook does, and in
   no set order with it: an add event may or may not include what a
   subscriber here wrote.
@@ -65,8 +175,17 @@ never reaches its "done" hook; its "end" hook fires all the same.
   its `ldaprenamedone` runs outside any operation, even when a request hook
   made it.
 
-## [onChange](../usage/plugins/ldap/on-change.md) hooks
+## onLdapChange
 
 - **onLdapEntryChange**: called after any write, with the entry before and
-  after it, and who made it
-- **onLdapChange**, **onLdapMailChange**…: derived from it
+  after it, and who made it.
+- **onLdapChange**, **onLdapMailChange**…: derived from it, and the
+  attribute ones fire only while the entry has the attribute configured for
+  them. A delete fires `onLdapEntryChange`, `onLdapChange` and
+  `onLdapMailChange` only.
+
+## Ordering
+
+Hooks run in the order their plugins loaded, but for the request hooks of
+authorization plugins, which run before every other plugin's, see
+[dependencies](dependencies.md#hook-execution-order).

package/docs/plugin-development/openapi.md

@@ -3,7 +3,15 @@
 The published API reference at <https://linagora.github.io/ldap-rest/api/> is
 generated from `openapi.json`, which itself is built statically by
 [`scripts/generate-openapi.ts`](../../scripts/generate-openapi.ts) — it walks
-every plugin's `api()` method and reads the JSDoc comments above each route.
+every plugin's `api()` method and reads the JSDoc comments above each route,
+and reads the declaration of every [`defineRoute`](routes.md) call.
+
+With `defineRoute` the declaration is the document: the generator takes its
+`summary`, `description`, `tags`, `params`, `query`, `body` and `responses`,
+and imports the exported schema constants it names. An `@openapi` block above
+the call still wins over what the declaration says — a `requestBody` it
+describes replaces the declared `body` schema whole, rather than merging into
+it — and a route registered with `app.<verb>(` still needs one.
 
 You don't need to touch the generator to enrich your plugin's documentation.
 Two JSDoc directives drive the entire pipeline:
@@ -139,6 +147,11 @@ npm run generate:openapi   # writes openapi.json
 npm run build:pages        # rebuilds the static site under _site/
 ```
 
+`openapi.json` is committed: it is what the site publishes, so a change to a
+route or to a schema it declares must come with a regenerated document. CI
+runs `npm run check:openapi`, which builds the spec and fails when the file
+differs, naming the first line at fault.
+
 Open `_site/api/index.html` to preview the Redoc rendering. The published
 site at <https://linagora.github.io/ldap-rest/api/> is rebuilt automatically
 on every `v*` tag push.

package/docs/plugin-development/options.md

@@ -0,0 +1,109 @@
+# Plugin options
+
+A core plugin declares its configuration options next to its code, in a
+`<plugin>.options.ts` file. A family that shares imports and lifecycle keeps
+one set per plugin in a single `<family>.options.ts` file, named after the
+family. `src/config/args.ts` concatenates those declarations,
+so the parser, the command line and the environment variables see the same
+entries as before. The plugin then reads typed values instead of casting
+`this.config`.
+
+## Declaring options
+
+```typescript
+// src/plugins/example/example.options.ts
+import { defineOptions, opt, type OptionsOf } from '../../config/options';
+
+export const exampleOptions = defineOptions({
+  example_url: opt.string({
+    env: 'DM_EXAMPLE_URL',
+    required: true,
+  }),
+  example_timeout: opt.number({
+    env: 'DM_EXAMPLE_TIMEOUT',
+    default: 5000,
+    min: 1,
+  }),
+  example_retry: opt.boolean({
+    env: 'DM_EXAMPLE_RETRY',
+    default: false,
+  }),
+  example_domains: opt.array({
+    env: 'DM_EXAMPLE_DOMAINS',
+    default: [],
+    plural: 'example-domains',
+    kind: 'identifiers',
+  }),
+});
+
+export type ExampleOptions = OptionsOf<typeof exampleOptions>;
+```
+
+The key is the `Config` name: `example_timeout` is `--example-timeout`,
+`DM_EXAMPLE_TIMEOUT` when the descriptor names that variable.
+
+Each declaration takes:
+
+| Field      | Meaning                                                             |
+| ---------- | ------------------------------------------------------------------- |
+| `env`      | Environment variable read when the CLI does not set the option      |
+| `default`  | Value kept when neither the CLI nor the environment sets the option |
+| `required` | Refuse an empty value instead of reading it as unset                |
+| `plural`   | Array only: CLI name of the plural form, without the leading `--`   |
+| `kind`     | Array only: how a value splits, see `ArrayKind` in `parseConfig.ts` |
+| `min/max`  | Number only: bounds checked when the option is read                 |
+| `choices`  | String only: the values the option accepts                          |
+
+## Reading options
+
+The plugin names the declaration as a static field, and asks for the values in
+its constructor:
+
+```typescript
+export default class Example extends DmPlugin {
+  static optionDefinitions = exampleOptions;
+  name = 'example';
+
+  private readonly settings: ExampleOptions;
+
+  constructor(server: DM) {
+    super(server);
+    this.settings = this.options(exampleOptions);
+  }
+}
+```
+
+`options(exampleOptions)` applies the defaults, copies array defaults and
+checks `required`, `min`, `max` and `choices`. The base constructor asks once,
+so a bad value stops the plugin from loading rather than failing at the first
+request. Each later call reads the configuration again rather than keeping
+the first values. `--plugin example:name:{...}` overrides still work: the view the
+plugin receives carries the merged configuration, and `options()` reads that
+view. Give it the same declaration object the class names in
+`optionDefinitions`: any other one is refused, so the generic type parameter
+cannot describe the wrong view.
+
+## Wiring it in
+
+Import the declaration in `src/config/args.ts` and spread it where the plugin's
+options used to be:
+
+```typescript
+import { exampleOptions } from '../plugins/example/example.options';
+import { toConfigEntries } from './options';
+
+const configArgs: ConfigTemplate = [
+  // ...
+  ...toConfigEntries(exampleOptions),
+];
+```
+
+The `Config` interface keeps the hand-written fields until every plugin has
+moved. A migrated plugin no longer reads them: it uses `options()`.
+
+Plugins outside the repository cannot add to `args.ts` yet, but they can
+declare options the same way and name them in `optionDefinitions`: the startup
+report subtracts those keys, and `options()` reads a declared `env` variable
+when the parser did not carry the key. An option without a declaration still
+reaches `this.config` from an unknown `--key value` pair, and the startup
+report names it.