nestjs-web-repl 1.0.0 → 2.0.0

package/README.md

@@ -35,7 +35,7 @@ import { WebReplModule } from 'nestjs-web-repl';
 
 @Module({
   imports: [
-    WebReplModule.forRoot({
+    WebReplModule.register({
       enabled: process.env.REPL_ENABLED === 'true',
     }),
   ],
@@ -51,7 +51,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 +118,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 +128,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 +197,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 +249,98 @@ 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
+
+This package ships a [Claude Code](https://claude.com/claude-code) skill that
+teaches coding agents how to wire in and use the REPL safely. After installing
+the package, run:
+
+```bash
+npx nestjs-web-repl install-skill
+```
+
+This writes `.claude/skills/nestjs-web-repl/SKILL.md` into your project; your
+agent picks it up on its next session. The command never clobbers a modified
+skill file silently — if you have edited it, re-run with `--force` to refresh it
+after upgrading the package.
 
 ## Limitations (v1)
 
@@ -322,15 +390,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/cli/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+export interface RunResult {
+    code: number;
+    out: string;
+    err: string;
+}
+export declare function run(argv: string[], cwd: string): RunResult;

package/dist/cli/index.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const install_skill_1 = require("./install-skill");
+const USAGE = `nestjs-web-repl — CLI
+
+Usage:
+  nestjs-web-repl install-skill [--force]   Install the Claude Code skill into
+                                            ./.claude/skills/nestjs-web-repl/
+
+Options:
+  --force    Overwrite an existing, locally modified SKILL.md
+  --help     Show this help
+`;
+function run(argv, cwd) {
+    const [subcommand, ...rest] = argv;
+    if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+        return { code: 0, out: USAGE, err: '' };
+    }
+    if (subcommand === 'install-skill') {
+        const force = rest.includes('--force');
+        try {
+            const { status, path } = (0, install_skill_1.installSkill)({ cwd, force });
+            switch (status) {
+                case 'created':
+                    return { code: 0, out: `created ${path}\n`, err: '' };
+                case 'up-to-date':
+                    return { code: 0, out: `up to date ${path}\n`, err: '' };
+                case 'updated':
+                    return { code: 0, out: `updated ${path}\n`, err: '' };
+                case 'differs':
+                    return {
+                        code: 1,
+                        out: '',
+                        err: `differs from the shipped version: ${path}\n` +
+                            `re-run with --force to overwrite\n`,
+                    };
+                default: {
+                    const _exhaustive = status;
+                    return { code: 1, out: '', err: `internal error: unhandled status ${String(_exhaustive)}\n` };
+                }
+            }
+        }
+        catch (err) {
+            return { code: 1, out: '', err: `error: ${err.message}\n` };
+        }
+    }
+    return { code: 2, out: '', err: `unknown command: ${subcommand}\n\n${USAGE}` };
+}
+if (require.main === module) {
+    const result = run(process.argv.slice(2), process.cwd());
+    if (result.out)
+        process.stdout.write(result.out);
+    if (result.err)
+        process.stderr.write(result.err);
+    process.exit(result.code);
+}

package/dist/cli/install-skill.d.ts

@@ -0,0 +1,17 @@
+export declare const SKILL_TARGET_SUBPATH: string;
+export type InstallStatus = 'created' | 'up-to-date' | 'differs' | 'updated';
+export interface InstallSkillOptions {
+    cwd: string;
+    force?: boolean;
+    sourcePath?: string;
+}
+export interface InstallSkillResult {
+    status: InstallStatus;
+    path: string;
+}
+/**
+ * Resolve the bundled skill source. Compiled to dist/cli/install-skill.js,
+ * so the package root is two levels up; skill/SKILL.md lives there.
+ */
+export declare function defaultSourcePath(): string;
+export declare function installSkill(options: InstallSkillOptions): InstallSkillResult;

package/dist/cli/install-skill.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_TARGET_SUBPATH = void 0;
+exports.defaultSourcePath = defaultSourcePath;
+exports.installSkill = installSkill;
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.SKILL_TARGET_SUBPATH = (0, path_1.join)('.claude', 'skills', 'nestjs-web-repl', 'SKILL.md');
+/**
+ * Resolve the bundled skill source. Compiled to dist/cli/install-skill.js,
+ * so the package root is two levels up; skill/SKILL.md lives there.
+ */
+function defaultSourcePath() {
+    return (0, path_1.join)(__dirname, '..', '..', 'skill', 'SKILL.md');
+}
+function installSkill(options) {
+    const { cwd, force = false } = options;
+    const sourcePath = options.sourcePath ?? defaultSourcePath();
+    const source = (0, fs_1.readFileSync)(sourcePath, 'utf8');
+    const path = (0, path_1.join)(cwd, exports.SKILL_TARGET_SUBPATH);
+    if (!(0, fs_1.existsSync)(path)) {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+        (0, fs_1.writeFileSync)(path, source);
+        return { status: 'created', path };
+    }
+    const current = (0, fs_1.readFileSync)(path, 'utf8');
+    if (current === source) {
+        return { status: 'up-to-date', path };
+    }
+    if (!force) {
+        return { status: 'differs', path };
+    }
+    (0, fs_1.writeFileSync)(path, source);
+    return { status: 'updated', path };
+}

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,12 +1,16 @@
 {
   "name": "nestjs-web-repl",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Expose a live NestJS REPL over the network (HTTP + SSE + Monaco UI).",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "nestjs-web-repl": "dist/cli/index.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "skill"
   ],
   "repository": {
     "type": "git",

package/skill/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: nestjs-web-repl
+description: Use when wiring a live, in-process REPL into a NestJS app over HTTP via the nestjs-web-repl package — adding WebReplModule to AppModule, gating the REPL behind an environment flag, or calling/debugging its POST command, SSE stream, or browser-UI routes.
+---
+
+# nestjs-web-repl
+
+## Overview
+
+`nestjs-web-repl` exposes a live NestJS REPL over HTTP: a POST command endpoint,
+a Server-Sent Events output stream, and a Monaco browser UI, backed by real
+`@nestjs/core` REPL sessions running inside the host app.
+
+## When to use this skill
+
+- Adding `WebReplModule` to a NestJS `AppModule` for the first time.
+- Reviewing or writing the code that enables/disables the REPL (the security
+  gate below is non-negotiable).
+- Calling or troubleshooting the `POST`/SSE/browser-UI routes at runtime.
+- Running the package's own examples (there's a `ts-node`-vs-`tsx` gotcha).
+
+## Security first — read before wiring
+
+The endpoints execute arbitrary code inside the running app **by design**. The
+library ships **no authentication** (intentional). Before adding the module:
+
+- Gate it behind an environment flag so it is OFF by default:
+  `enabled: process.env.REPL_ENABLED === 'true'`.
+- Never enable it in production without your own authentication or network
+  restriction in front of the routes.
+- A disabled module 404s every route and does not subscribe to the adapter —
+  keep it that way.
+
+## Wire it up
+
+Add the module to your `AppModule`:
+
+```ts
+import { Module } from '@nestjs/common';
+import { WebReplModule } from 'nestjs-web-repl';
+
+@Module({
+  imports: [
+    WebReplModule.register({
+      enabled: process.env.REPL_ENABLED === 'true',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Config-driven `enabled` (async form):
+
+```ts
+WebReplModule.registerAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    enabled: config.get('REPL_ENABLED') === 'true',
+  }),
+});
+```
+
+## Use it
+
+Three routes are registered (default base path `repl`), keyed by a channel name:
+
+| Route | Purpose |
+|---|---|
+| `POST repl/{channel}` | Send a line of code to execute. |
+| `GET repl/{channel}` | Server-Sent Events stream of output for the channel. |
+| `GET repl/{channel}/ui` | Monaco editor + terminal browser UI. |
+
+```bash
+# stream output (leave running in one terminal)
+curl -N http://localhost:3000/repl/main
+
+# in another terminal, run a command on the same channel
+curl -X POST http://localhost:3000/repl/main \
+  -H 'content-type: application/json' \
+  -d '{"command":"1 + 1"}'
+```
+
+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 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) 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` —
+  `tsx`/esbuild strips the decorator metadata NestJS DI needs. See "Limitations"
+  in the README.
+
+## Common mistakes
+
+- Enabling the REPL unconditionally (or defaulting `enabled` to `true`) —
+  always key it off an environment flag that defaults to off.
+- Running a README example with `tsx` and hitting missing-provider/DI errors —
+  use `ts-node` instead.