nestjs-web-repl 1.1.0 → 2.0.1

package/README.md

@@ -7,19 +7,18 @@ so `get(SomeService)`, `resolve(...)`, `select(...)`, and friends all work exact
 they do in the local REPL — except reachable over HTTP, from anywhere, against a
 running server.
 
-> ## ⚠️ Security warning — read this before enabling anything
+> ## ⚠️ Security
 >
-> **These endpoints execute arbitrary code inside your running application.**
-> A command like `require('child_process').execSync('...')` runs with the full
-> privileges of your Node process. This library ships with **no authentication,
-> no authorization, and no rate limiting**. The `enabled` option is the *only*
-> built-in safety rail, and it is a blunt boolean — it does not check who is
-> asking.
+> These endpoints run arbitrary code inside your app, with the full privileges of
+> your Node process. That's the whole point — it's a debugging tool — and it's
+> also the risk: anyone who can reach an enabled endpoint can run anything your
+> app can.
 >
-> Do not expose these routes on a public-facing port. Do not enable this in
-> production unless you have put your own auth in front of it (see
-> [Securing it](#securing-it) below). Treat this exactly like you would treat
-> giving someone a shell on your server — because that is what it is.
+> The module ships no authentication of its own; `enabled` is an on/off switch,
+> not a lock. Control access yourself: gate `enabled` behind an environment
+> variable and put your own guard in front of the routes ([Securing it](#securing-it)).
+>
+> Guarded and on a trusted network, it's a safe way to inspect a running app.
 
 ## Install
 
@@ -35,7 +34,7 @@ import { WebReplModule } from 'nestjs-web-repl';
 
 @Module({
   imports: [
-    WebReplModule.forRoot({
+    WebReplModule.register({
       enabled: process.env.REPL_ENABLED === 'true',
     }),
   ],
@@ -51,7 +50,7 @@ resolves from the whole DI container, not just the module that imports
 
 A runnable example lives in [`example/`](./example): `example/cat.service.ts`
 registers a trivial `CatService`, `example/app.module.ts` wires up
-`WebReplModule.forRoot(...)`, and `example/main.ts` boots it. Run it with:
+`WebReplModule.register(...)`, and `example/main.ts` boots it. Run it with:
 
 ```bash
 REPL_ENABLED=true PORT=3000 npx ts-node -T example/main.ts
@@ -118,7 +117,8 @@ curl -X POST http://localhost:3000/repl/dev \
 ## Securing it
 
 Because the module ships no auth, the supported way to lock this down is to
-disable the built-in controller and register your own subclass with guards:
+subclass the built-in controller, add your own guard, and pass it in via the
+`controller` extra:
 
 ```ts
 import { Controller, UseGuards } from '@nestjs/common';
@@ -127,31 +127,35 @@ import { AdminGuard } from './admin.guard';
 
 @Controller('internal/repl')
 @UseGuards(AdminGuard)
-export class SecureReplController extends WebReplController {}
+class SecureReplController extends WebReplController {}
 ```
 
 ```ts
 @Module({
   imports: [
-    WebReplModule.forRoot({
+    WebReplModule.register({
       enabled: process.env.REPL_ENABLED === 'true',
-      registerController: false, // don't register the unguarded default controller
+      controller: SecureReplController, // replaces the unguarded default controller
     }),
   ],
-  controllers: [SecureReplController], // register yours instead
 })
 export class AppModule {}
 ```
 
-> **Note:** `registerController: false` only takes effect via the synchronous
-> `forRoot(...)`. `forRootAsync(...)` always registers the default,
-> **unguarded** `WebReplController`, because whether to declare a controller is
-> a static, module-definition-time decision in Nest, and `forRootAsync`'s
-> options aren't resolved until DI runs (after controllers are already fixed).
-> If you need async configuration (e.g. options from a `ConfigService`) *and*
-> a guarded controller, resolve your options synchronously up front (read env
-> vars / config directly) and call `forRoot(...)`, or put a guard in front of
-> the route at the HTTP-adapter/middleware level instead.
+`controller` is available to both `register` and `registerAsync` — it is a
+static, module-definition-time choice, so it's passed alongside `useFactory`/
+`inject` rather than resolved by it:
+
+```ts
+WebReplModule.registerAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    enabled: config.get('REPL_ENABLED') === 'true',
+  }),
+  controller: SecureReplController,
+});
+```
 
 ## Adapter / multi-instance
 
@@ -192,7 +196,9 @@ solves this with an **ownership + fan-out** protocol:
 By default this coordination happens via `InMemoryWebReplAdapter`, which only
 works within a single process (fine for local dev / single-instance
 deployments). For real multi-instance deployments, provide your own adapter
-that implements:
+via the `adapter` extra — a ready instance, `{ useClass, imports }`, or
+`{ useFactory, inject, imports }` (all DI-capable, so the adapter can itself
+depend on other providers) — that implements:
 
 ```ts
 export interface WebReplAdapter {
@@ -242,37 +248,83 @@ export class RedisWebReplAdapter implements WebReplAdapter, OnModuleDestroy {
 ```
 
 ```ts
-WebReplModule.forRoot({
+// as a ready-made instance
+WebReplModule.register({
   enabled: process.env.REPL_ENABLED === 'true',
   adapter: new RedisWebReplAdapter(),
   instanceId: process.env.HOSTNAME, // shows up in `command` SSE events and
                                      // internal webrepl:sys claim messages
 });
+
+// or let Nest construct it (and its dependencies) for you
+WebReplModule.register({
+  enabled: process.env.REPL_ENABLED === 'true',
+  adapter: { useClass: RedisWebReplAdapter, imports: [RedisModule] },
+});
+
+// or build it with a factory
+WebReplModule.register({
+  enabled: process.env.REPL_ENABLED === 'true',
+  adapter: {
+    useFactory: (redis: RedisService) => new RedisWebReplAdapter(redis),
+    inject: [RedisService],
+    imports: [RedisModule],
+  },
+});
 ```
 
 ## Options (`WebReplModuleOptions`)
 
 | Option              | Type             | Default                    | Notes                                              |
 | ------------------- | ---------------- | --------------------------- | --------------------------------------------------- |
-| `enabled`           | `boolean`        | *(required)*                | When `false`, the module registers nothing at all.  |
-| `adapter`           | `WebReplAdapter` | `InMemoryWebReplAdapter`    | Provide for multi-instance coordination.            |
+| `enabled`           | `boolean`        | *(required)*                | When `false`, routes 404 and the module does not subscribe to the adapter. |
 | `instanceId`        | `string`         | random `inst_xxxxxxxx`      | Shown in `command` SSE events and internal `webrepl:sys` claim/release messages. |
 | `sessionTtl`        | `number` (ms)    | `1_800_000` (30 min)        | Idle time before a channel's ownership is released. |
 | `replayBufferSize`  | `number`         | `200`                       | Events kept per channel for SSE `Last-Event-ID` replay. |
 | `heartbeatInterval` | `number` (ms)    | `15_000`                    | SSE `system` `{ ping: true }` interval.             |
 | `ownerHeartbeatInterval` | `number` (ms) | `10_000`                | How often an instance re-announces `claim` for each channel it owns, keeping its ownership lease alive. |
 | `ownerLeaseTtl`     | `number` (ms)    | `30_000`                    | How long an ownership record is trusted since the last claim/heartbeat, before a stale owner's channel may be taken over. Enforced minimum `ownerHeartbeatInterval * 2` (a live owner always keeps a full heartbeat interval of slack against delivery jitter); if the configured value is below that, it's clamped up to `ownerHeartbeatInterval * 2` and a warning is logged (never throws). |
-| `registerController`| `boolean`        | `true`                      | Set `false` to omit the default controller (see [Securing it](#securing-it)). `forRoot` only. |
 
-`WebReplModule.forRootAsync({ useFactory, inject, imports })` is also available
-for options that need DI (e.g. reading a `ConfigService`); see the
-`registerController` caveat above.
+`register`/`registerAsync` also accept two "extras", passed alongside the
+options above (or alongside `useFactory`/`inject`/`imports` for the async
+form) rather than through them, since both are static, module-definition-time
+choices:
+
+| Extra        | Type                  | Default              | Notes                                              |
+| ------------ | --------------------- | --------------------- | --------------------------------------------------- |
+| `controller` | `Type<WebReplController>` | built-in `WebReplController` | Bring your own controller (subclass + guards). See [Securing it](#securing-it). |
+| `adapter`    | `WebReplAdapter \| Type<WebReplAdapter> \| { useClass, imports? } \| { useFactory, inject?, imports? }` | `InMemoryWebReplAdapter` | Multi-instance coordination. See [Adapter / multi-instance](#adapter--multi-instance). |
+
+`WebReplModule.registerAsync({ useFactory, inject, imports, controller?, adapter? })`
+is also available for options that need DI (e.g. reading a `ConfigService`).
 
 ## Exports
 
 `WebReplModule`, `WebReplController`, `WebReplService`, `InMemoryWebReplAdapter`,
-and the types `WebReplAdapter`, `WebReplModuleOptions`, `WebReplModuleAsyncOptions`,
-`WebReplEvent`, `SseEventType`.
+and `WEB_REPL_OPTIONS` (the DI token for the resolved options, useful when
+injecting them into a sibling-registered controller subclass), plus the types
+`WebReplAdapter`, `WebReplModuleOptions`, `WebReplModuleExtras`,
+`WebReplAdapterConfig`, `WebReplEvent`, `SseEventType`.
+
+## Migrating from 1.x → 2.0
+
+- `WebReplModule.forRoot(...)` → `WebReplModule.register(...)`.
+- `WebReplModule.forRootAsync(...)` → `WebReplModule.registerAsync(...)`.
+- `adapter` is no longer an option resolved by `useFactory`; it's a static
+  "extra" passed alongside the options (or alongside `useFactory`/`inject` for
+  the async form), and now also accepts `{ useClass, imports? }` or
+  `{ useFactory, inject?, imports? }` in addition to a ready instance — see
+  [Adapter / multi-instance](#adapter--multi-instance).
+- `registerController: false` is gone. To run your own guarded controller
+  instead of the default, subclass `WebReplController`, add `@UseGuards(...)`,
+  and pass it as the `controller` extra to `register`/`registerAsync` — see
+  [Securing it](#securing-it). Unlike the old `registerController` flag, this
+  works identically for both the sync and async form.
+- A disabled module (`enabled: false`) now still registers the
+  controller/service, but every route 404s and the module never subscribes to
+  the adapter — it no longer silently registers nothing. If you were relying
+  on a disabled module contributing zero routes/providers to the Nest module
+  graph, that is no longer the case.
 
 ## AI skill
 
@@ -337,15 +389,16 @@ We tell you this because the honest thing to do is let you judge the code on
 its merits rather than guess at its origins. If you are skeptical of AI-written
 code, here is what to actually look at:
 
-- **The tests.** 62 automated tests, including a two-instance end-to-end test
+- **The tests.** 83 automated tests, including a two-instance end-to-end test
   that proves cross-instance command routing and output fan-out, and an
   execution-proof test that resolves a real provider through the live REPL
   context. `npm test`, `npm run build`, and `npx tsc --noEmit` are all green.
 - **The commit history.** The real TDD trail is preserved — failing test,
   implementation, fixes — including several rounds where review caught genuine
   defects (the trickiest: `node:repl` completion detection on modern Node, and
-  a runtime-vs-registration security bug where `forRootAsync` could have
-  shipped the arbitrary-code endpoint live with `enabled: false`).
+  a runtime-vs-registration security bug where an earlier async-registration
+  API could have shipped the arbitrary-code endpoint live with
+  `enabled: false`; `registerAsync` now enforces `enabled` at runtime instead).
 - **The security invariants** are documented in [`AGENTS.md`](./AGENTS.md) and
   enforced by tests, not left as prose.
 

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { WebReplModule } from './web-repl.module';
 export { WebReplController } from './web-repl.controller';
 export { WebReplService } from './web-repl.service';
 export { InMemoryWebReplAdapter } from './adapters/in-memory-web-repl.adapter';
+export { WEB_REPL_OPTIONS } from './constants';
 export type { WebReplAdapter } from './interfaces/web-repl-adapter.interface';
-export type { WebReplModuleOptions, WebReplModuleAsyncOptions, } from './interfaces/web-repl-options.interface';
+export type { WebReplModuleOptions, WebReplModuleExtras, WebReplAdapterConfig, } from './interfaces/web-repl-options.interface';
 export type { WebReplEvent, SseEventType, } from './interfaces/web-repl-messages.interface';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryWebReplAdapter = exports.WebReplService = exports.WebReplController = exports.WebReplModule = void 0;
+exports.WEB_REPL_OPTIONS = exports.InMemoryWebReplAdapter = exports.WebReplService = exports.WebReplController = exports.WebReplModule = void 0;
 var web_repl_module_1 = require("./web-repl.module");
 Object.defineProperty(exports, "WebReplModule", { enumerable: true, get: function () { return web_repl_module_1.WebReplModule; } });
 var web_repl_controller_1 = require("./web-repl.controller");
@@ -9,3 +9,5 @@ var web_repl_service_1 = require("./web-repl.service");
 Object.defineProperty(exports, "WebReplService", { enumerable: true, get: function () { return web_repl_service_1.WebReplService; } });
 var in_memory_web_repl_adapter_1 = require("./adapters/in-memory-web-repl.adapter");
 Object.defineProperty(exports, "InMemoryWebReplAdapter", { enumerable: true, get: function () { return in_memory_web_repl_adapter_1.InMemoryWebReplAdapter; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "WEB_REPL_OPTIONS", { enumerable: true, get: function () { return constants_1.WEB_REPL_OPTIONS; } });

package/dist/interfaces/web-repl-options.interface.d.ts

@@ -1,10 +1,10 @@
-import type { ModuleMetadata } from '@nestjs/common';
+import type { ModuleMetadata, Type } from '@nestjs/common';
 import type { WebReplAdapter } from './web-repl-adapter.interface';
+import type { WebReplController } from '../web-repl.controller';
+/** Runtime options — the only thing registerAsync's factory resolves. */
 export interface WebReplModuleOptions {
-    /** Required. When false the module registers nothing. */
+    /** Required. When false the module is inert: every route 404s, no subscribe. */
     enabled: boolean;
-    /** Multi-instance coordination. Defaults to InMemoryWebReplAdapter. */
-    adapter?: WebReplAdapter;
     /** Identifies this instance in ownership/system messages. Auto-generated if omitted. */
     instanceId?: string;
     /** Idle ms before a session is disposed. Default 30 min. */
@@ -13,28 +13,28 @@ export interface WebReplModuleOptions {
     replayBufferSize?: number;
     /** SSE ping-comment interval in ms. Default 15000. */
     heartbeatInterval?: number;
-    /**
-     * How often an instance re-announces `claim` for each channel it currently
-     * owns, keeping its ownership lease alive. Default 10000.
-     */
+    /** How often an instance re-announces `claim` for channels it owns. Default 10000. */
     ownerHeartbeatInterval?: number;
     /**
-     * How long an ownership record is trusted since the last claim/heartbeat
-     * seen for it, before another instance may take over a channel whose owner
-     * has gone silent (e.g. crashed or was killed without a clean shutdown).
-     * Default 30000. Enforced minimum: `ownerHeartbeatInterval * 2` -- a live
-     * owner must always have at least one full heartbeat interval of slack
-     * against publish/delivery jitter, or a single late-arriving heartbeat
-     * could make it look stale to a peer and get preempted. If the configured
-     * value is below that minimum, the effective lease is clamped up to
-     * `ownerHeartbeatInterval * 2` and a warning is logged (this never
-     * throws).
+     * How long an ownership record is trusted since the last claim/heartbeat.
+     * Default 30000. Clamped to at least `ownerHeartbeatInterval * 2` (see
+     * WebReplService's constructor).
      */
     ownerLeaseTtl?: number;
-    /** When false, the default controller is not registered (user registers a subclass). Default true. */
-    registerController?: boolean;
 }
-export interface WebReplModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    useFactory: (...args: any[]) => WebReplModuleOptions | Promise<WebReplModuleOptions>;
+/** Adapter configured as a DI-capable provider (or a ready instance). */
+export type WebReplAdapterConfig = WebReplAdapter | Type<WebReplAdapter> | {
+    useClass: Type<WebReplAdapter>;
+    imports?: ModuleMetadata['imports'];
+} | {
+    useFactory: (...args: any[]) => WebReplAdapter | Promise<WebReplAdapter>;
     inject?: any[];
+    imports?: ModuleMetadata['imports'];
+};
+/** Static composition — passed synchronously to both register and registerAsync. */
+export interface WebReplModuleExtras {
+    /** Bring your own controller (extend WebReplController + add guards). Default: built-in. */
+    controller?: Type<WebReplController>;
+    /** Multi-instance coordination. Default: InMemoryWebReplAdapter. */
+    adapter?: WebReplAdapterConfig;
 }

package/dist/web-repl.controller.js

@@ -51,11 +51,9 @@ let WebReplController = class WebReplController {
         this.options = options;
     }
     async dispatch(channel, body) {
-        // CRITICAL: forRootAsync always registers this controller regardless
-        // of the resolved `enabled` value (providers/controllers must be
-        // declared statically before useFactory ever runs). Re-check at
-        // request time so a disabled async module 404s on every route, just
-        // like the sync forRoot(enabled: false) path that registers nothing.
+        // CRITICAL: register/registerAsync always register this controller;
+        // `enabled` is enforced at runtime so a disabled module 404s on every
+        // route.
         if (!this.options.enabled)
             throw new common_1.NotFoundException();
         if (typeof body?.command !== 'string' || body.command.trim().length === 0) {

package/dist/web-repl.module-definition.d.ts

@@ -0,0 +1,10 @@
+import { type DynamicModule, type Provider } from '@nestjs/common';
+import type { WebReplModuleOptions, WebReplModuleExtras, WebReplAdapterConfig } from './interfaces/web-repl-options.interface';
+type BuiltAdapter = {
+    provider: Provider;
+    imports: NonNullable<DynamicModule['imports']>;
+};
+/** Maps a WebReplAdapterConfig to the WEB_REPL_ADAPTER provider + any imports. */
+export declare function buildAdapterProvider(config: WebReplAdapterConfig | undefined): BuiltAdapter;
+export declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<WebReplModuleOptions, "register", "create", WebReplModuleExtras>, MODULE_OPTIONS_TOKEN: string | symbol;
+export {};

package/dist/web-repl.module-definition.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_OPTIONS_TOKEN = exports.ConfigurableModuleClass = void 0;
+exports.buildAdapterProvider = buildAdapterProvider;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const constants_1 = require("./constants");
+const in_memory_web_repl_adapter_1 = require("./adapters/in-memory-web-repl.adapter");
+const web_repl_service_1 = require("./web-repl.service");
+const web_repl_controller_1 = require("./web-repl.controller");
+const build_repl_context_1 = require("./context/build-repl-context");
+const CONTEXT_FACTORY = 'WEB_REPL_CONTEXT_FACTORY';
+/** Maps a WebReplAdapterConfig to the WEB_REPL_ADAPTER provider + any imports. */
+function buildAdapterProvider(config) {
+    if (config === undefined) {
+        return {
+            provider: { provide: constants_1.WEB_REPL_ADAPTER, useClass: in_memory_web_repl_adapter_1.InMemoryWebReplAdapter },
+            imports: [],
+        };
+    }
+    if (typeof config === 'function') {
+        return { provider: { provide: constants_1.WEB_REPL_ADAPTER, useClass: config }, imports: [] };
+    }
+    if ('useClass' in config) {
+        return {
+            provider: { provide: constants_1.WEB_REPL_ADAPTER, useClass: config.useClass },
+            imports: config.imports ?? [],
+        };
+    }
+    if ('useFactory' in config) {
+        return {
+            provider: {
+                provide: constants_1.WEB_REPL_ADAPTER,
+                useFactory: config.useFactory,
+                inject: config.inject ?? [],
+            },
+            imports: config.imports ?? [],
+        };
+    }
+    // Otherwise it must be a ready-made WebReplAdapter instance — verify it
+    // actually looks like one so a malformed block (e.g. a typo'd `usClass`)
+    // fails fast at registration instead of silently becoming a useValue.
+    if (typeof config !== 'object' ||
+        config === null ||
+        typeof config.publish !== 'function' ||
+        typeof config.subscribe !== 'function') {
+        throw new Error('WebReplModule: invalid adapter config — expected a WebReplAdapter instance, a Type, or a { useClass } / { useFactory } block');
+    }
+    return { provider: { provide: constants_1.WEB_REPL_ADAPTER, useValue: config }, imports: [] };
+}
+// The builder generates its own options token (MODULE_OPTIONS_TOKEN). We keep
+// the stable WEB_REPL_OPTIONS token for WebReplService/WebReplController to
+// inject, aliasing it to the builder's token. The transform closure runs at
+// register()-time (after this module is fully evaluated), so it reads
+// `optionsToken`, assigned right after build() below.
+let optionsToken;
+const definition = new common_1.ConfigurableModuleBuilder()
+    .setClassMethodName('register')
+    .setExtras({ controller: undefined, adapter: undefined }, (def, extras) => {
+    const adapter = buildAdapterProvider(extras.adapter);
+    return {
+        ...def,
+        imports: [...(def.imports ?? []), ...adapter.imports],
+        controllers: [extras.controller ?? web_repl_controller_1.WebReplController],
+        providers: [
+            ...(def.providers ?? []),
+            { provide: constants_1.WEB_REPL_OPTIONS, useExisting: optionsToken },
+            adapter.provider,
+            {
+                provide: CONTEXT_FACTORY,
+                useFactory: (moduleRef) => () => (0, build_repl_context_1.buildReplContext)(moduleRef),
+                inject: [core_1.ModuleRef],
+            },
+            { provide: constants_1.WEB_REPL_CLOCK, useValue: () => Date.now() },
+            web_repl_service_1.WebReplService,
+        ],
+        exports: [web_repl_service_1.WebReplService, constants_1.WEB_REPL_OPTIONS],
+    };
+})
+    .build();
+exports.ConfigurableModuleClass = definition.ConfigurableModuleClass, exports.MODULE_OPTIONS_TOKEN = definition.MODULE_OPTIONS_TOKEN;
+optionsToken = exports.MODULE_OPTIONS_TOKEN;

package/dist/web-repl.module.d.ts

@@ -1,8 +1,3 @@
-import { type DynamicModule } from '@nestjs/common';
-import type { WebReplModuleOptions, WebReplModuleAsyncOptions } from './interfaces/web-repl-options.interface';
-export declare class WebReplModule {
-    static forRoot(options: WebReplModuleOptions): DynamicModule;
-    static forRootAsync(async: WebReplModuleAsyncOptions): DynamicModule;
-    private static assemble;
-    private static sharedProviders;
+import { ConfigurableModuleClass } from './web-repl.module-definition';
+export declare class WebReplModule extends ConfigurableModuleClass {
 }

package/dist/web-repl.module.js

@@ -5,78 +5,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var WebReplModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebReplModule = void 0;
 const common_1 = require("@nestjs/common");
-const core_1 = require("@nestjs/core");
-const constants_1 = require("./constants");
-const in_memory_web_repl_adapter_1 = require("./adapters/in-memory-web-repl.adapter");
-const web_repl_service_1 = require("./web-repl.service");
-const web_repl_controller_1 = require("./web-repl.controller");
-const build_repl_context_1 = require("./context/build-repl-context");
-const CONTEXT_FACTORY = 'WEB_REPL_CONTEXT_FACTORY';
-let WebReplModule = WebReplModule_1 = class WebReplModule {
-    static forRoot(options) {
-        if (!options.enabled)
-            return { module: WebReplModule_1 };
-        return this.assemble([{ provide: constants_1.WEB_REPL_OPTIONS, useValue: options }], options);
-    }
-    static forRootAsync(async) {
-        const optionsProvider = {
-            provide: constants_1.WEB_REPL_OPTIONS,
-            useFactory: async.useFactory,
-            inject: async.inject ?? [],
-        };
-        // registerController is read from resolved options only at request time
-        // in the sense that this module has no way to inspect the value
-        // useFactory will eventually produce until it runs -- and providers /
-        // controllers must be declared statically. So forRootAsync always
-        // registers the default controller; callers who need to omit it should
-        // use forRoot() with a statically-known `registerController: false`.
-        return {
-            module: WebReplModule_1,
-            imports: async.imports ?? [],
-            providers: [optionsProvider, ...this.sharedProviders()],
-            controllers: [web_repl_controller_1.WebReplController],
-            // WEB_REPL_OPTIONS must be exported alongside WebReplService: since
-            // WebReplController (and any subclass of it, per the README's
-            // "Securing it" pattern) now injects WEB_REPL_OPTIONS to enforce
-            // `enabled` at runtime (see CRITICAL 1), a caller who mounts their
-            // own guarded subclass controller on a SIBLING module (with
-            // registerController: false) needs to be able to resolve it too.
-            exports: [web_repl_service_1.WebReplService, constants_1.WEB_REPL_OPTIONS],
-        };
-    }
-    static assemble(optionProviders, options) {
-        return {
-            module: WebReplModule_1,
-            providers: [...optionProviders, ...this.sharedProviders()],
-            controllers: options.registerController === false ? [] : [web_repl_controller_1.WebReplController],
-            exports: [web_repl_service_1.WebReplService, constants_1.WEB_REPL_OPTIONS],
-        };
-    }
-    static sharedProviders() {
-        return [
-            {
-                provide: constants_1.WEB_REPL_ADAPTER,
-                useFactory: (opts) => opts.adapter ?? new in_memory_web_repl_adapter_1.InMemoryWebReplAdapter(),
-                inject: [constants_1.WEB_REPL_OPTIONS],
-            },
-            {
-                provide: CONTEXT_FACTORY,
-                useFactory: (moduleRef) => () => (0, build_repl_context_1.buildReplContext)(moduleRef),
-                inject: [core_1.ModuleRef],
-            },
-            {
-                provide: constants_1.WEB_REPL_CLOCK,
-                useValue: () => Date.now(),
-            },
-            web_repl_service_1.WebReplService,
-        ];
-    }
+const web_repl_module_definition_1 = require("./web-repl.module-definition");
+let WebReplModule = class WebReplModule extends web_repl_module_definition_1.ConfigurableModuleClass {
 };
 exports.WebReplModule = WebReplModule;
-exports.WebReplModule = WebReplModule = WebReplModule_1 = __decorate([
+exports.WebReplModule = WebReplModule = __decorate([
     (0, common_1.Module)({})
 ], WebReplModule);

package/dist/web-repl.service.js

@@ -64,12 +64,12 @@ let WebReplService = class WebReplService {
         }
     }
     async onModuleInit() {
-        // CRITICAL: `enabled` is the product's only safety rail. forRoot()
-        // already refuses to register anything when disabled, but
-        // forRootAsync() resolves options at DI time and always registers this
-        // service/controller -- so this runtime check is what keeps a
-        // config-driven `enabled: false` (e.g. from forRootAsync) from
-        // silently subscribing to the command bus and executing arbitrary code.
+        // CRITICAL: `enabled` is the product's only safety rail. Both
+        // register() and registerAsync() always register this
+        // service/controller (providers/controllers must be declared
+        // statically) -- so this runtime check is what keeps a config-driven
+        // `enabled: false` (e.g. from registerAsync) from silently subscribing
+        // to the command bus and executing arbitrary code.
         if (!this.enabled)
             return;
         await this.adapter.subscribe(constants_1.TOPICS.cmd, (m) => this.onCmd(this.parse(m)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-web-repl",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "description": "Expose a live NestJS REPL over the network (HTTP + SSE + Monaco UI).",
   "license": "MIT",
   "main": "dist/index.js",

package/skill/SKILL.md

@@ -41,7 +41,7 @@ import { WebReplModule } from 'nestjs-web-repl';
 
 @Module({
   imports: [
-    WebReplModule.forRoot({
+    WebReplModule.register({
       enabled: process.env.REPL_ENABLED === 'true',
     }),
   ],
@@ -52,7 +52,7 @@ export class AppModule {}
 Config-driven `enabled` (async form):
 
 ```ts
-WebReplModule.forRootAsync({
+WebReplModule.registerAsync({
   imports: [ConfigModule],
   inject: [ConfigService],
   useFactory: (config: ConfigService) => ({
@@ -85,12 +85,17 @@ Open `http://localhost:3000/repl/main/ui` in a browser for the interactive UI.
 
 ## When you need more
 
+- **Authentication:** subclass `WebReplController`, decorate it with
+  `@UseGuards(...)`, and pass it as `controller:` to `register`/`registerAsync`.
+  See "Securing it" in the package README.
 - **Multiple app instances** (load-balanced replicas): the default in-memory
-  adapter is per-process; supply a shared adapter so a command and its output
-  reach the owning instance. See "Adapter / multi-instance" in the package
-  README.
+  adapter is per-process; supply a shared adapter via the `adapter` extra
+  (a ready instance, `{ useClass, imports }`, or `{ useFactory, inject, imports }`)
+  so a command and its output reach the owning instance. See "Adapter /
+  multi-instance" in the package README.
 - **Custom adapter:** implement the adapter interface (publish/subscribe over
-  the message topics). See "Adapter / multi-instance" in the README.
+  the message topics) and pass it via the `adapter` extra. See "Adapter /
+  multi-instance" in the README.
 - **Options** (base path, TTLs, heartbeats) and **exported symbols:** see
   "Options" and "Exports" in the README.
 - **Runnable example gotcha:** run examples with `ts-node`, not `tsx` —