@super-line/plugin-inspector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,193 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  inspector: () => inspector
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@super-line/core");
+var encoder = new TextEncoder();
+function encodedByteSize(encoded) {
+  return typeof encoded === "string" ? encoder.encode(encoded).length : encoded.byteLength;
+}
+async function buildInspectedContract(contract) {
+  let toJsonSchema;
+  try {
+    const mod = await import("@standard-community/standard-json");
+    toJsonSchema = mod.toJsonSchema;
+  } catch {
+    return (0, import_core.classifyContract)(contract);
+  }
+  const schemas = /* @__PURE__ */ new Set();
+  (0, import_core.classifyContract)(contract, (s) => {
+    schemas.add(s);
+    return void 0;
+  });
+  const converted = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...schemas].map(
+      (s) => toJsonSchema(s).then(
+        (j) => {
+          converted.set(s, j);
+        },
+        () => {
+        }
+        // unsupported vendor / missing per-vendor converter -> structure-only for this entry
+      )
+    )
+  );
+  return (0, import_core.classifyContract)(contract, (s) => converted.get(s));
+}
+function inspector(opts = {}) {
+  const redact = new Set(opts.redact ?? []);
+  function safeSnapshot(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+    if (value === null) return null;
+    const t = typeof value;
+    if (t === "bigint") return `${value.toString()}n`;
+    if (t === "function") return "[Function]";
+    if (t === "symbol") return value.toString();
+    if (t !== "object") return value;
+    const obj = value;
+    if (obj instanceof Date) return obj.toISOString();
+    if (seen.has(obj)) return "[Circular]";
+    if (depth >= 6) return "[MaxDepth]";
+    seen.add(obj);
+    try {
+      if (Array.isArray(obj)) return obj.slice(0, 1e3).map((v) => safeSnapshot(v, depth + 1, seen));
+      const ctor = Object.getPrototypeOf(obj)?.constructor?.name;
+      const out = {};
+      if (ctor && ctor !== "Object") out["#type"] = ctor;
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = redact.has(k) ? "[Redacted]" : safeSnapshot(v, depth + 1, seen);
+      }
+      return out;
+    } finally {
+      seen.delete(obj);
+    }
+  }
+  function snapshotEvent(event) {
+    switch (event.type) {
+      case "msg.request":
+      case "msg.serverRequest":
+        return { ...event, input: safeSnapshot(event.input) };
+      case "msg.response":
+      case "msg.serverReply":
+        return event.ok ? { ...event, output: safeSnapshot(event.output) } : event;
+      case "msg.event":
+      case "msg.broadcast":
+      case "msg.publish":
+      case "store.write":
+        return { ...event, data: safeSnapshot(event.data) };
+      default:
+        return event;
+    }
+  }
+  let channel;
+  let originNodeId = "";
+  let encode = (v) => JSON.stringify(v);
+  return {
+    name: "inspector",
+    setup(ctx) {
+      channel = ctx.channel("events");
+      originNodeId = ctx.instanceId;
+      encode = (v) => ctx.serializer.encode(v);
+    },
+    onEvent(event) {
+      if (!channel) return;
+      const snapped = snapshotEvent(event);
+      const payload = (0, import_core.eventPayload)(snapped);
+      const envelope = {
+        event: snapped,
+        ts: Date.now(),
+        originNodeId,
+        byteSize: payload === void 0 ? void 0 : encodedByteSize(encode(payload))
+      };
+      channel.publish(envelope);
+    },
+    connection: {
+      role: import_core.INSPECTOR_ROLE,
+      subprotocol: import_core.INSPECTOR_SUBPROTOCOL,
+      contract: import_core.InspectorContract,
+      handlers: (ctx) => ({
+        getContract: () => buildInspectedContract(ctx.contract),
+        getTopology: () => ctx.cluster.topology(),
+        listConnections: () => ctx.cluster.connections(),
+        getNode: async () => ({ nodeId: ctx.instanceId, nodeName: ctx.nodeName, rooms: ctx.local.rooms, topics: ctx.local.topics }),
+        getConn: async (input) => {
+          const id = input?.id;
+          if (!id) throw new import_core.SuperLineError("BAD_REQUEST", "getConn requires an id");
+          const local = ctx.conns.find((cn) => cn.id === id);
+          if (local) {
+            return {
+              descriptor: ctx.describe(local),
+              ctx: safeSnapshot(local.ctx),
+              data: safeSnapshot(local.data),
+              ctxAvailable: true
+            };
+          }
+          const remote = await ctx.connectionById(id);
+          if (!remote) throw new import_core.SuperLineError("NOT_FOUND", `Unknown connection: ${id}`);
+          return { descriptor: remote, ctxAvailable: false };
+        },
+        listStores: async () => ctx.storeInfos(),
+        listResources: async (input) => {
+          const { store: name, ...opts2 } = input;
+          if (!ctx.storeInfos().some((s) => s.name === name)) throw new import_core.SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
+          return ctx.store(name).list(opts2);
+        },
+        searchPrincipals: async (input) => {
+          const { store: name, ...opts2 } = input;
+          if (!ctx.storeInfos().some((s) => s.name === name)) throw new import_core.SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
+          return ctx.store(name).searchPrincipals(opts2);
+        },
+        readResource: async (input) => {
+          const { store: name, id } = input;
+          if (!ctx.storeInfos().some((s) => s.name === name)) throw new import_core.SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
+          const handle = ctx.store(name);
+          const resource = await handle.read(id);
+          if (!resource) throw new import_core.SuperLineError("NOT_FOUND", `No resource: ${name}/${id}`);
+          let data = resource.data;
+          try {
+            const replica = handle.open(id);
+            data = replica.getSnapshot();
+            replica.close();
+          } catch {
+          }
+          return { data: safeSnapshot(data), accessRules: resource.accessRules };
+        }
+      })
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  inspector
+});

package/dist/index.d.cts

@@ -0,0 +1,17 @@
+import { SuperLinePlugin } from '@super-line/server';
+
+/** Options for {@link inspector}. */
+interface InspectorOptions {
+    /** Field names to mask (`[Redacted]`) in snapshotted payloads / ctx / data. */
+    redact?: string[];
+}
+/**
+ * The Control Center inspector, packaged as a plugin. It taps every request/event/store write, snapshots +
+ * field-redacts the payloads, and publishes them (cluster-wide) on its own plugin channel; and it declares a
+ * plugin-owned, observer-invisible connection class (the `superline.inspector.v1` subprotocol) that serves
+ * Control Center clients the `InspectorContract` — `getContract`, `getTopology`, `getConn`, … and the
+ * `events` feed. Register it with `plugins: [inspector()]`. **Dev / trusted-network only.**
+ */
+declare function inspector(opts?: InspectorOptions): SuperLinePlugin;
+
+export { type InspectorOptions, inspector };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { SuperLinePlugin } from '@super-line/server';
+
+/** Options for {@link inspector}. */
+interface InspectorOptions {
+    /** Field names to mask (`[Redacted]`) in snapshotted payloads / ctx / data. */
+    redact?: string[];
+}
+/**
+ * The Control Center inspector, packaged as a plugin. It taps every request/event/store write, snapshots +
+ * field-redacts the payloads, and publishes them (cluster-wide) on its own plugin channel; and it declares a
+ * plugin-owned, observer-invisible connection class (the `superline.inspector.v1` subprotocol) that serves
+ * Control Center clients the `InspectorContract` — `getContract`, `getTopology`, `getConn`, … and the
+ * `events` feed. Register it with `plugins: [inspector()]`. **Dev / trusted-network only.**
+ */
+declare function inspector(opts?: InspectorOptions): SuperLinePlugin;
+
+export { type InspectorOptions, inspector };

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/index.ts
+import {
+  SuperLineError,
+  INSPECTOR_ROLE,
+  INSPECTOR_SUBPROTOCOL,
+  InspectorContract,
+  classifyContract,
+  eventPayload
+} from "@super-line/core";
+var encoder = new TextEncoder();
+function encodedByteSize(encoded) {
+  return typeof encoded === "string" ? encoder.encode(encoded).length : encoded.byteLength;
+}
+async function buildInspectedContract(contract) {
+  let toJsonSchema;
+  try {
+    const mod = await import("@standard-community/standard-json");
+    toJsonSchema = mod.toJsonSchema;
+  } catch {
+    return classifyContract(contract);
+  }
+  const schemas = /* @__PURE__ */ new Set();
+  classifyContract(contract, (s) => {
+    schemas.add(s);
+    return void 0;
+  });
+  const converted = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...schemas].map(
+      (s) => toJsonSchema(s).then(
+        (j) => {
+          converted.set(s, j);
+        },
+        () => {
+        }
+        // unsupported vendor / missing per-vendor converter -> structure-only for this entry
+      )
+    )
+  );
+  return classifyContract(contract, (s) => converted.get(s));
+}
+function inspector(opts = {}) {
+  const redact = new Set(opts.redact ?? []);
+  function safeSnapshot(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
+    if (value === null) return null;
+    const t = typeof value;
+    if (t === "bigint") return `${value.toString()}n`;
+    if (t === "function") return "[Function]";
+    if (t === "symbol") return value.toString();
+    if (t !== "object") return value;
+    const obj = value;
+    if (obj instanceof Date) return obj.toISOString();
+    if (seen.has(obj)) return "[Circular]";
+    if (depth >= 6) return "[MaxDepth]";
+    seen.add(obj);
+    try {
+      if (Array.isArray(obj)) return obj.slice(0, 1e3).map((v) => safeSnapshot(v, depth + 1, seen));
+      const ctor = Object.getPrototypeOf(obj)?.constructor?.name;
+      const out = {};
+      if (ctor && ctor !== "Object") out["#type"] = ctor;
+      for (const [k, v] of Object.entries(obj)) {
+        out[k] = redact.has(k) ? "[Redacted]" : safeSnapshot(v, depth + 1, seen);
+      }
+      return out;
+    } finally {
+      seen.delete(obj);
+    }
+  }
+  function snapshotEvent(event) {
+    switch (event.type) {
+      case "msg.request":
+      case "msg.serverRequest":
+        return { ...event, input: safeSnapshot(event.input) };
+      case "msg.response":
+      case "msg.serverReply":
+        return event.ok ? { ...event, output: safeSnapshot(event.output) } : event;
+      case "msg.event":
+      case "msg.broadcast":
+      case "msg.publish":
+      case "store.write":
+        return { ...event, data: safeSnapshot(event.data) };
+      default:
+        return event;
+    }
+  }
+  let channel;
+  let originNodeId = "";
+  let encode = (v) => JSON.stringify(v);
+  return {
+    name: "inspector",
+    setup(ctx) {
+      channel = ctx.channel("events");
+      originNodeId = ctx.instanceId;
+      encode = (v) => ctx.serializer.encode(v);
+    },
+    onEvent(event) {
+      if (!channel) return;
+      const snapped = snapshotEvent(event);
+      const payload = eventPayload(snapped);
+      const envelope = {
+        event: snapped,
+        ts: Date.now(),
+        originNodeId,
+        byteSize: payload === void 0 ? void 0 : encodedByteSize(encode(payload))
+      };
+      channel.publish(envelope);
+    },
+    connection: {
+      role: INSPECTOR_ROLE,
+      subprotocol: INSPECTOR_SUBPROTOCOL,
+      contract: InspectorContract,
+      handlers: (ctx) => ({
+        getContract: () => buildInspectedContract(ctx.contract),
+        getTopology: () => ctx.cluster.topology(),
+        listConnections: () => ctx.cluster.connections(),
+        getNode: async () => ({ nodeId: ctx.instanceId, nodeName: ctx.nodeName, rooms: ctx.local.rooms, topics: ctx.local.topics }),
+        getConn: async (input) => {
+          const id = input?.id;
+          if (!id) throw new SuperLineError("BAD_REQUEST", "getConn requires an id");
+          const local = ctx.conns.find((cn) => cn.id === id);
+          if (local) {
+            return {
+              descriptor: ctx.describe(local),
+              ctx: safeSnapshot(local.ctx),
+              data: safeSnapshot(local.data),
+              ctxAvailable: true
+            };
+          }
+          const remote = await ctx.connectionById(id);
+          if (!remote) throw new SuperLineError("NOT_FOUND", `Unknown connection: ${id}`);
+          return { descriptor: remote, ctxAvailable: false };
+        },
+        listStores: async () => ctx.storeInfos(),
+        listResources: async (input) => {
+          const { store: name, ...opts2 } = input;
+          if (!ctx.storeInfos().some((s) => s.name === name)) throw new SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
+          return ctx.store(name).list(opts2);
+        },
+        searchPrincipals: async (input) => {
+          const { store: name, ...opts2 } = input;
+          if (!ctx.storeInfos().some((s) => s.name === name)) throw new SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
+          return ctx.store(name).searchPrincipals(opts2);
+        },
+        readResource: async (input) => {
+          const { store: name, id } = input;
+          if (!ctx.storeInfos().some((s) => s.name === name)) throw new SuperLineError("NOT_FOUND", `Unknown store: ${name}`);
+          const handle = ctx.store(name);
+          const resource = await handle.read(id);
+          if (!resource) throw new SuperLineError("NOT_FOUND", `No resource: ${name}/${id}`);
+          let data = resource.data;
+          try {
+            const replica = handle.open(id);
+            data = replica.getSnapshot();
+            replica.close();
+          } catch {
+          }
+          return { data: safeSnapshot(data), accessRules: resource.accessRules };
+        }
+      })
+    }
+  };
+}
+export {
+  inspector
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@super-line/plugin-inspector",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Control Center inspector for super-line, packaged as a plugin — taps + a plugin-owned CC connection.",
+  "license": "MIT",
+  "author": "Mert",
+  "keywords": [
+    "super-line",
+    "plugin",
+    "inspector",
+    "control-center",
+    "observability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mertdogar/super-line.git",
+    "directory": "packages/plugin-inspector"
+  },
+  "homepage": "https://mertdogar.github.io/super-line/",
+  "bugs": "https://github.com/mertdogar/super-line/issues",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@standard-community/standard-json": "^0.3.5",
+    "@super-line/core": "^0.10.0"
+  },
+  "peerDependencies": {
+    "@super-line/server": "^0.10.0"
+  },
+  "devDependencies": {
+    "@super-line/server": "^0.10.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}