@feasibleone/blong-gogo 1.19.1 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.20.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.19.1...blong-gogo-v1.20.0) (2026-05-11)
+
+
+### Features
+
+* add runtime introspection endpoints for development troubleshooting ([#144](https://github.com/feasibleone/blong/issues/144)) ([81d665c](https://github.com/feasibleone/blong/commit/81d665c3d09bdd767ee78e824d4e529fed5f00d5))
+
 ## [1.19.1](https://github.com/feasibleone/blong/compare/blong-gogo-v1.19.0...blong-gogo-v1.19.1) (2026-05-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },

package/src/SystemDebug.ts

@@ -0,0 +1,118 @@
+import type {IConfigRuntime, IGateway, ILog, IRegistry} from '@feasibleone/blong/types';
+import {Internal} from '@feasibleone/blong/types';
+import type {FastifyInstance} from 'fastify';
+import fp from 'fastify-plugin';
+
+interface IConfig {
+    enabled: boolean;
+    routePrefix: string;
+    auth: false | 'jwt';
+}
+
+interface IGatewayWithPlugins extends IGateway {
+    registerPlugin(plugin: unknown, options?: unknown): void;
+}
+
+interface IRpcServerWithInfo {
+    info(): object;
+}
+
+// The api object is captured by reference so that configRuntime — which is set
+// on it after infra items are constructed (load.ts) — is visible at request time.
+interface IApiRef {
+    log?: ILog;
+    gateway?: IGatewayWithPlugins;
+    registry?: IRegistry;
+    rpcServer?: IRpcServerWithInfo;
+    configRuntime?: IConfigRuntime;
+}
+
+export default class SystemDebug extends Internal {
+    #config: IConfig = {
+        enabled: false,
+        routePrefix: '/api/sys',
+        auth: false,
+    };
+
+    #apiRef: IApiRef;
+
+    public constructor(config: IConfig, apiRef: IApiRef) {
+        super({log: apiRef.log});
+        this.merge(this.#config, config);
+        this.#apiRef = apiRef;
+    }
+
+    public async init(): Promise<void> {
+        if (!this.#config.enabled || !this.#apiRef.gateway) return;
+
+        this.log?.warn?.(
+            'systemDebug is enabled — introspection endpoints are active; do not enable in production',
+        );
+
+        const apiRef = this.#apiRef;
+        const prefix = this.#config.routePrefix;
+        const authConfig = this.#config.auth;
+
+        const plugin = fp(
+            async (server: FastifyInstance) => {
+                // GET /api/sys/config — effective runtime configuration snapshot
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/config`,
+                    config: {auth: authConfig},
+                    handler: async () => apiRef.configRuntime?.rawSnapshot ?? {},
+                });
+
+                // GET /api/sys/ports — registered adapter/orchestrator port definitions
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/ports`,
+                    config: {auth: authConfig},
+                    handler: async () => ({
+                        ports: Array.from(apiRef.registry?.ports.keys() ?? []),
+                    }),
+                });
+
+                // GET /api/sys/methods — registered handler method groups with handler counts
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/methods`,
+                    config: {auth: authConfig},
+                    handler: async () => ({
+                        methods: Array.from(apiRef.registry?.methods.entries() ?? []).map(
+                            ([name, handlers]) => ({
+                                name,
+                                handlerCount: handlers.length,
+                            }),
+                        ),
+                    }),
+                });
+
+                // GET /api/sys/modules — registered realm modules.
+                // Symbol keys (used internally for system-tagged infrastructure items)
+                // are excluded because they are not JSON-serialisable.
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/modules`,
+                    config: {auth: authConfig},
+                    handler: async () => ({
+                        modules: Array.from(apiRef.registry?.modules.keys() ?? []).filter(
+                            (k): k is string => typeof k === 'string',
+                        ),
+                    }),
+                });
+
+                // GET /api/sys/rpc — internal RPC server address info
+                server.route({
+                    method: 'GET',
+                    url: `${prefix}/rpc`,
+                    config: {auth: authConfig},
+                    handler: async () => apiRef.rpcServer?.info() ?? {},
+                });
+            },
+            {name: 'system-debug'},
+        );
+
+        apiRef.gateway!.registerPlugin(plugin);
+    }
+}

package/src/load.ts

@@ -375,6 +375,7 @@ export default async function loadRealm<T extends TSchema>(
             rpcServer: {},
             gateway: {},
             restFs: {},
+            systemDebug: {},
         });
         items = topoSort([
             {
@@ -464,6 +465,11 @@ export default async function loadRealm<T extends TSchema>(
                           deps: ['log', 'gateway'],
                           load: () => import('./RestFs.ts'),
                       },
+                      {
+                          name: 'systemDebug',
+                          deps: ['log', 'gateway', 'registry', 'rpcServer'],
+                          load: () => import('./SystemDebug.ts'),
+                      },
                       {
                           name: 'registry',
                           deps: [