@feasibleone/blong-gogo 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Bug Fixes
+
+* improve model and mock ([20b530c](https://github.com/feasibleone/blong/commit/20b530cc9d00284a52ad99b63b95fbb7bd4e4e82))
+
 ## [1.19.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.18.1...blong-gogo-v1.19.0) (2026-04-29)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.19.0",
+  "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

@@ -21,7 +21,6 @@ import {Type, type TSchema} from 'typebox';
 import merge from 'ut-function.merge';
 import {methodParts} from './lib.ts';
 
-import minimist from 'minimist';
 import ConfigRuntime from './ConfigRuntime.ts';
 import layerProxy from './layerProxy.ts';
 import RealmImpl, {type IRealm} from './Realm.ts';
@@ -189,16 +188,15 @@ interface IConstructor {
     new (config?: object, api?: object): object;
 }
 
-const argConfigs = minimist(process.argv.slice(2))._;
-
 function activeConfigs<T extends TSchema>(
     mod: IModuleConfig<T>,
     configNames: string[],
+    platformConfigs: string[],
 ): (boolean | object)[] {
     return (
         (['default'] as string[])
             .concat(configNames)
-            .concat(argConfigs)
+            .concat(platformConfigs)
             .map(name => (mod.config as unknown as Record<string, unknown>)?.[name])
             .filter(Boolean) as (boolean | object)[]
     ).concat({pkg: mod.pkg, children: mod.children, url: mod.url});
@@ -377,6 +375,7 @@ export default async function loadRealm<T extends TSchema>(
             rpcServer: {},
             gateway: {},
             restFs: {},
+            systemDebug: {},
         });
         items = topoSort([
             {
@@ -466,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: [
@@ -502,7 +506,7 @@ export default async function loadRealm<T extends TSchema>(
             return fn;
         });
     }
-    loadedConfigs.push(...activeConfigs(mod, configNames));
+    loadedConfigs.push(...activeConfigs(mod, configNames, platformApi.configs));
     const {loadedConfig, configRuntime} = await platformApi.loadConfig(parentConfig);
     if (loadedConfig) loadedConfigs.push(loadedConfig);
 

package/src/loadBrowser.ts

@@ -11,8 +11,8 @@ declare global {
     }
 }
 
-var performance = globalThis.performance || {};
-var performanceNow =
+const performance = globalThis.performance || {};
+const performanceNow =
     performance.now ||
     performance.mozNow ||
     performance.msNow ||
@@ -25,9 +25,9 @@ var performanceNow =
 // generate timestamp or delta
 // see http://nodejs.org/api/process.html#process_process_hrtime
 function hrtime(previousTimestamp?: HRTime): HRTime {
-    var clocktime = performanceNow.call(performance) * 1e-3;
-    var seconds = Math.floor(clocktime);
-    var nanoseconds = Math.floor((clocktime % 1) * 1e9);
+    const clockTime = performanceNow.call(performance) * 1e-3;
+    let seconds = Math.floor(clockTime);
+    let nanoseconds = Math.floor((clockTime % 1) * 1e9);
     if (previousTimestamp) {
         seconds = seconds - previousTimestamp[0];
         nanoseconds = nanoseconds - previousTimestamp[1];
@@ -79,4 +79,5 @@ export default load.bind(null, {
     },
     statSync: (() => undefined) as unknown as import('node:fs').StatSyncFn,
     timing: timing(hrtime),
+    configs: ['browser'],
 });

package/src/loadServer.ts

@@ -2,6 +2,7 @@ import {watch} from 'chokidar';
 import type {Dirent} from 'fs';
 import {existsSync, readFileSync, statSync, writeFileSync} from 'fs';
 import {readdir} from 'fs/promises';
+import minimist from 'minimist';
 import {createRequire} from 'node:module';
 import {hrtime} from 'node:process';
 import {basename, dirname, extname, join, relative, resolve} from 'path';
@@ -45,4 +46,5 @@ export default load.bind(null, {
     statSync,
     watch,
     timing: timing(hrtime),
+    configs: ['server', ...minimist(process.argv.slice(2))._],
 });