nestjs-web-repl 1.0.0 → 1.1.0

package/README.md

@@ -274,6 +274,21 @@ for options that need DI (e.g. reading a `ConfigService`); see the
 and the types `WebReplAdapter`, `WebReplModuleOptions`, `WebReplModuleAsyncOptions`,
 `WebReplEvent`, `SseEventType`.
 
+## 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)
 
 - **Monaco loads from a CDN** (`cdn.jsdelivr.net`) inside the `/ui` page — the

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/package.json

@@ -1,12 +1,16 @@
 {
   "name": "nestjs-web-repl",
-  "version": "1.0.0",
+  "version": "1.1.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,105 @@
+---
+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.forRoot({
+      enabled: process.env.REPL_ENABLED === 'true',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Config-driven `enabled` (async form):
+
+```ts
+WebReplModule.forRootAsync({
+  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
+
+- **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.
+- **Custom adapter:** implement the adapter interface (publish/subscribe over
+  the message topics). 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.