nestjs-web-repl 0.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
@@ -348,6 +363,60 @@ intent and do not, and cannot, technically enforce anything, nor do they bind
 GitHub's own hosting. Using an AI coding assistant to help you *work with* this
 library is entirely fine and expected.
 
+## Releasing
+
+Releases are **fully automated**. Merging a PR to `main` with releasable
+[Conventional Commits](https://www.conventionalcommits.org/) triggers
+`.github/workflows/release.yml`, which runs the full test suite and then
+[semantic-release](https://semantic-release.gitbook.io/):
+
+| Commit type            | Version bump      |
+| ---------------------- | ----------------- |
+| `fix:`                 | patch (x.y.**z**) |
+| `feat:`                | minor (x.**y**.0) |
+| `feat!:` / `BREAKING CHANGE:` in body | major (**x**.0.0) |
+| `docs:` `chore:` `test:` `ci:` `refactor:` | no release |
+
+It computes the next version, updates `CHANGELOG.md`, publishes to npm
+(**tokenless via OIDC trusted publishing, with provenance attached
+automatically**), tags the commit, cuts a GitHub Release, and commits the
+version/changelog bump back to `main` as `chore(release): x.y.z [skip ci]`.
+Do not bump `version` in `package.json` by hand.
+
+### One-time bootstrap (maintainer, once)
+
+npm's OIDC trusted publishing cannot perform a package's *first* publish, so a
+maintainer does this once:
+
+1. **Create the package on npm with a placeholder:**
+   ```bash
+   npm login
+   npm version 0.0.0 --no-git-tag-version   # temp, do not commit
+   npm publish --access public
+   git checkout -- package.json               # restore working version
+   ```
+   Do **not** create a git tag for `0.0.0`; with no tags semantic-release's
+   first automated release is `1.0.0`.
+2. **Register the Trusted Publisher** at
+   `https://www.npmjs.com/package/nestjs-web-repl/access` → *Trusted Publishers*
+   → GitHub Actions: owner `p-dim-popov`, repository `nestjs-web-repl`, workflow
+   `release.yml` (leave environment blank). After this, no token is needed.
+3. (Optional, after `1.0.0` ships) `npm deprecate nestjs-web-repl@0.0.0 "placeholder"`.
+
+### Verifying the first real release
+
+After the bootstrap, the next merge to `main` containing a `feat:`/`fix:` commit
+should produce `1.0.0`. Confirm:
+
+- `npm view nestjs-web-repl version` → `1.0.0`
+- the npm package page shows a provenance / "Published via GitHub Actions" badge
+- a `v1.0.0` git tag and a matching GitHub Release with generated notes exist
+- `CHANGELOG.md` and a `chore(release): 1.0.0` commit are on `main`
+- the `release.yml` run is green
+
+If the publish step fails with an auth error, the Trusted Publisher registration
+(step 2) is missing or its repo/workflow fields don't match exactly.
+
 ## Contributing
 
 Contributions are welcome — see [`CONTRIBUTING.md`](./CONTRIBUTING.md). AI-

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,13 +1,31 @@
 {
   "name": "nestjs-web-repl",
-  "version": "0.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",
+    "url": "git+https://github.com/p-dim-popov/nestjs-web-repl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/p-dim-popov/nestjs-web-repl/issues"
+  },
+  "homepage": "https://github.com/p-dim-popov/nestjs-web-repl#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run --passWithNoTests",
@@ -24,11 +42,14 @@
     "@nestjs/core": "^11",
     "@nestjs/platform-express": "^11",
     "@nestjs/testing": "^11",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@swc/core": "^1.15.43",
     "@types/node": "^20",
     "@types/supertest": "^6",
     "reflect-metadata": "^0.2",
     "rxjs": "^7",
+    "semantic-release": "^25.0.8",
     "supertest": "^7",
     "ts-node": "^10.9.2",
     "typescript": "^5",

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.