zumito-framework 1.23.3 → 1.25.0

package/dist/ZumitoFramework.js

@@ -25,6 +25,7 @@ import { ErrorType } from './definitions/ErrorType.js';
 import { MongoService } from './services/MongoService.js';
 import { registerDefaultExecutionRules } from './modules/core/baseModule/defaultRules.js';
 import { DatabaseManager } from 'zumito-db';
+import { registerFrameworkInspector, startInspectorFileWriter } from './utils/Inspector.js';
 // import better-logging
 betterLogging(console);
 /**
@@ -148,6 +149,7 @@ export class ZumitoFramework {
         ServiceContainer.addService(CommandManager, [], true, this.commands);
         ServiceContainer.addService(EventManager, [], true, this.eventManager);
         ServiceContainer.addService(SlashCommandRefresher, [], true, new SlashCommandRefresher(this));
+        registerFrameworkInspector(this);
         if (settings.logLevel) {
             console.logLevel = settings.logLevel;
         }
@@ -155,6 +157,7 @@ export class ZumitoFramework {
             .then(() => {
             if (callback)
                 callback(this);
+            startInspectorFileWriter(this);
         })
             .catch((err) => {
             console.error(err, err.message, err.stack, err.name);
@@ -188,7 +191,7 @@ export class ZumitoFramework {
         }
     }
     async initializeDatabase() {
-        const mongoUri = this.settings?.mongoQueryString || process.env.MONGO_URI;
+        const mongoUri = this.settings?.mongoQueryString || process.env.DATABASE_URI;
         const dbSettings = this.settings.database;
         let config;
         if (dbSettings?.default) {
@@ -208,7 +211,7 @@ export class ZumitoFramework {
         else {
             console.error('[🗄️🔴] No database configured.');
             console.error('  Set database.default in zumito.config.ts (memory, tingo, mongo, sqlite)');
-            console.error('  or set MONGO_URI / mongoQueryString for MongoDB.');
+            console.error('  or set DATABASE_URI / mongoQueryString for MongoDB.');
             process.exit(1);
         }
         if (this.settings.models) {

package/dist/definitions/config/moduleHelpers.d.ts

@@ -0,0 +1,32 @@
+import { ZumitoFramework } from '../../ZumitoFramework.js';
+import type { ModuleEntry } from '../settings/FrameworkSettings.js';
+/**
+ * Creates a type-safe factory function that returns a `ModuleEntry`.
+ * Reads the module name from the nearest `package.json` by walking up
+ * from the caller's location.
+ *
+ * @example
+ * ```ts
+ * // admin/index.ts
+ * export const adminModule = createModuleEntry<AdminConfig>(import.meta.url);
+ *
+ * // Consumer's zumito.config.ts
+ * adminModule({ colors: { primary: '#ff0000' } })
+ * ```
+ */
+export declare function createModuleEntry<T = Record<string, any>>(metaUrl: string): (config?: T) => ModuleEntry;
+/**
+ * Retrieves the module-specific configuration from the framework settings
+ * by matching the module's package name against the `modules` array.
+ *
+ * Modules that are registered as plain strings in the `modules` array
+ * (without config) will return an empty object.
+ *
+ * @example
+ * ```ts
+ * import { getModuleConfig } from 'zumito-framework';
+ *
+ * const config = getModuleConfig<MyConfig>(framework, import.meta.url);
+ * ```
+ */
+export declare function getModuleConfig<T = Record<string, any>>(framework: ZumitoFramework | undefined, metaUrl: string): T;

package/dist/definitions/config/moduleHelpers.js

@@ -0,0 +1,71 @@
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { existsSync } from 'fs';
+function findPackageJson(startPath) {
+    let dir = startPath;
+    for (let i = 0; i < 10; i++) {
+        const candidate = resolve(dir, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+function readModuleName(metaUrl) {
+    const filePath = fileURLToPath(metaUrl);
+    const callerDir = dirname(filePath);
+    const pkgPath = findPackageJson(callerDir);
+    if (!pkgPath)
+        return null;
+    const require = createRequire(pkgPath);
+    return require(pkgPath)?.name ?? null;
+}
+/**
+ * Creates a type-safe factory function that returns a `ModuleEntry`.
+ * Reads the module name from the nearest `package.json` by walking up
+ * from the caller's location.
+ *
+ * @example
+ * ```ts
+ * // admin/index.ts
+ * export const adminModule = createModuleEntry<AdminConfig>(import.meta.url);
+ *
+ * // Consumer's zumito.config.ts
+ * adminModule({ colors: { primary: '#ff0000' } })
+ * ```
+ */
+export function createModuleEntry(metaUrl) {
+    const name = readModuleName(metaUrl);
+    if (!name) {
+        throw new Error(`createModuleEntry: could not read 'name' from package.json near ${metaUrl}`);
+    }
+    return (config) => ({ name, config });
+}
+/**
+ * Retrieves the module-specific configuration from the framework settings
+ * by matching the module's package name against the `modules` array.
+ *
+ * Modules that are registered as plain strings in the `modules` array
+ * (without config) will return an empty object.
+ *
+ * @example
+ * ```ts
+ * import { getModuleConfig } from 'zumito-framework';
+ *
+ * const config = getModuleConfig<MyConfig>(framework, import.meta.url);
+ * ```
+ */
+export function getModuleConfig(framework, metaUrl) {
+    if (!framework)
+        return {};
+    const name = readModuleName(metaUrl);
+    if (!name)
+        return {};
+    const modules = framework.settings?.modules ?? [];
+    const entry = modules.find((m) => typeof m !== 'string' && m.name === name);
+    return (entry?.config ?? {});
+}

package/dist/index.d.ts

@@ -42,6 +42,7 @@ export { CommandBinds } from './definitions/commands/CommandBinds.js';
 export { Injectable } from './definitions/decorators/Injectable.decorator.js';
 export { LauncherConfig } from './definitions/config/LauncherConfig.js';
 export { defineConfig } from './definitions/config/defineConfig.js';
+export { createModuleEntry, getModuleConfig } from './definitions/config/moduleHelpers.js';
 export type { ModuleEntry } from './definitions/settings/FrameworkSettings.js';
 export { ModuleParameters } from './definitions/parameters/ModuleParameters.js';
 export { ZumitoFramework, FrameworkSettings, Command, Module, ModuleDeclaration, ModuleRequeriments, CommandParameters, CommandArguments, FrameworkEvent, Translation, TranslationManager, ApiResponse, SelectMenuParameters, CommandType, CommandArgDefinition, CommandChoiceDefinition, ButtonPressed, ButtonPressedParams, TextFormatter, EmojiFallback, DatabaseConfigLoader, PresenceDataRule, RuledPresenceData, StatusManagerOptions, discord, EventParameters, ServiceContainer, GuildDataGetter, SlashCommandRefresher, CommandParser, ErrorHandler, ErrorType, Route, RouteMethod, InteractionHandler, CommandManager, InviteUrlGenerator, PrefixResolver, CommandExecutionChecker, DatabaseManager, };

package/dist/index.js

@@ -29,6 +29,7 @@ import { DatabaseManager } from 'zumito-db';
 export { Collection, Field, HasMany, BelongsTo, HasOne, Migration, Repository, QueryBuilder } from 'zumito-db';
 export { Injectable } from './definitions/decorators/Injectable.decorator.js';
 export { defineConfig } from './definitions/config/defineConfig.js';
+export { createModuleEntry, getModuleConfig } from './definitions/config/moduleHelpers.js';
 ServiceContainer.addService(TextFormatter, []);
 ServiceContainer.addService(EmojiFallback, [discord.Client.name, TranslationManager.name]);
 ServiceContainer.addService(GuildDataGetter, [ZumitoFramework.name]);

package/dist/services/ServiceContainer.d.ts

@@ -5,6 +5,12 @@ declare class ServiceContainerManager {
     getServiceByName<T>(serviceName: string): T;
     addInstance(serviceClass: any, instance: any): void;
     hasService(serviceClass: any): boolean;
+    getAllServiceEntries(): Array<{
+        name: string;
+        dependencies: string[];
+        singleton: boolean;
+        hasInstance: boolean;
+    }>;
 }
 export declare const ServiceContainer: ServiceContainerManager;
 export {};

package/dist/services/ServiceContainer.js

@@ -62,6 +62,18 @@ class ServiceContainerManager {
         const serviceName = typeof serviceClass == 'string' ? serviceClass : serviceClass.name;
         return this.services.has(serviceName);
     }
+    getAllServiceEntries() {
+        const entries = [];
+        for (const [name, svc] of this.services) {
+            entries.push({
+                name,
+                dependencies: svc.dependencies,
+                singleton: svc.singleton,
+                hasInstance: svc.instance !== undefined,
+            });
+        }
+        return entries;
+    }
 }
 if (!global.ServiceContainer)
     global.ServiceContainer = new ServiceContainerManager();

package/dist/services/managers/CommandManager.js

@@ -42,6 +42,8 @@ export class CommandManager {
         if (!filePath.endsWith('.js') && !filePath.endsWith('.ts')) {
             return;
         }
+        if (filePath.endsWith('.d.ts'))
+            return;
         const counter = (this.importCounters.get(filePath) || 0) + 1;
         this.importCounters.set(filePath, counter);
         const baseName = path.basename(filePath).split('.').slice(0, -1).join('.');

package/dist/utils/Inspector.d.ts

@@ -0,0 +1,61 @@
+import { ZumitoFramework } from '../ZumitoFramework.js';
+export interface FrameworkSnapshot {
+    version: string;
+    uptime: number;
+    discord: {
+        status: 'connected' | 'disconnected';
+        user: {
+            id: string;
+            tag: string;
+        } | null;
+        guildCount: number;
+    };
+    database: {
+        connected: boolean;
+        driver: string;
+    };
+    commands: {
+        total: number;
+        items: Array<{
+            name: string;
+            type: string;
+            description: string;
+            aliases: string[];
+            categories: string[];
+            hidden: boolean;
+        }>;
+    };
+    modules: {
+        total: number;
+        items: Array<{
+            name: string;
+            displayName: string;
+            status: string;
+            dependencies: string[];
+            commandCount: number;
+            eventCount: number;
+        }>;
+    };
+    services: {
+        total: number;
+        items: Array<{
+            name: string;
+            singleton: boolean;
+            hasInstance: boolean;
+            dependencies: string[];
+        }>;
+    };
+    events: {
+        total: number;
+        items: Array<{
+            name: string;
+            source: string;
+        }>;
+    };
+}
+/**
+ * Write the inspector snapshot to .zumito/inspector-state.json in the current
+ * working directory. Returns a cleanup function that stops the write interval.
+ */
+export declare function startInspectorFileWriter(framework: ZumitoFramework): () => void;
+export declare function registerFrameworkInspector(framework: ZumitoFramework): void;

package/dist/utils/Inspector.js

@@ -0,0 +1,194 @@
+import { createRequire } from 'module';
+import * as fs from 'fs';
+import * as path from 'path';
+import { ServiceContainer } from '../services/ServiceContainer.js';
+const require = createRequire(import.meta.url);
+/**
+ * Write the inspector snapshot to .zumito/inspector-state.json in the current
+ * working directory. Returns a cleanup function that stops the write interval.
+ */
+export function startInspectorFileWriter(framework) {
+    const startTime = Date.now();
+    let pkg = {};
+    try {
+        pkg = require('../../package.json');
+    }
+    catch { /* ignore */ }
+    let lastJson = '';
+    let timer;
+    const write = () => {
+        const state = {
+            version: pkg.version || 'unknown',
+            uptime: Date.now() - startTime,
+            discord: {
+                status: framework.client?.isReady() ? 'connected' : 'disconnected',
+                user: framework.client?.user
+                    ? { id: framework.client.user.id, tag: framework.client.user.tag }
+                    : null,
+                guildCount: framework.client?.guilds?.cache?.size ?? 0,
+            },
+            database: {
+                connected: !!framework.db,
+                driver: framework.db ? getDriverName(framework) : 'none',
+            },
+            commands: serializeCommands(framework),
+            modules: serializeModules(framework),
+            services: serializeServices(),
+            events: serializeEvents(framework),
+        };
+        const json = JSON.stringify(state);
+        if (json === lastJson) {
+            return;
+        }
+        lastJson = json;
+        try {
+            const dir = path.join(process.cwd(), '.zumito');
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(path.join(dir, 'inspector-state.json'), json, 'utf-8');
+        }
+        catch {
+            // can't write – silently ignore
+        }
+    };
+    // Write immediately, then every 3s
+    write();
+    timer = setInterval(write, 3000);
+    return () => {
+        if (timer) {
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+}
+export function registerFrameworkInspector(framework) {
+    const startTime = Date.now();
+    let pkg = {};
+    try {
+        pkg = require('../../package.json');
+    }
+    catch {
+        // fallback if package.json can't be read
+    }
+    const inspector = {
+        getSnapshot() {
+            const state = {
+                version: pkg.version || 'unknown',
+                uptime: Date.now() - startTime,
+                discord: {
+                    status: framework.client?.isReady() ? 'connected' : 'disconnected',
+                    user: framework.client?.user
+                        ? { id: framework.client.user.id, tag: framework.client.user.tag }
+                        : null,
+                    guildCount: framework.client?.guilds?.cache?.size ?? 0,
+                },
+                database: {
+                    connected: !!framework.db,
+                    driver: framework.db ? getDriverName(framework) : 'none',
+                },
+                commands: serializeCommands(framework),
+                modules: serializeModules(framework),
+                services: serializeServices(),
+                events: serializeEvents(framework),
+            };
+            return JSON.stringify(state);
+        },
+        getCommands() {
+            return JSON.stringify(serializeCommands(framework));
+        },
+        getModules() {
+            return JSON.stringify(serializeModules(framework));
+        },
+        getServices() {
+            return JSON.stringify(serializeServices());
+        },
+        getEvents() {
+            return JSON.stringify(serializeEvents(framework));
+        },
+    };
+    try {
+        globalThis.__ZUMITO_INSPECT__ = inspector;
+    }
+    catch {
+        // globalThis not available (non-Node environment?)
+    }
+}
+function getDriverName(framework) {
+    try {
+        const driver = framework.db.getDriver?.();
+        if (driver) {
+            return driver.constructor?.name || 'custom';
+        }
+    }
+    catch {
+        // ignore
+    }
+    return 'unknown';
+}
+function serializeCommands(framework) {
+    const items = [];
+    const allCommands = framework.commands?.getAll();
+    if (allCommands) {
+        for (const [, cmd] of allCommands) {
+            items.push({
+                name: cmd.name,
+                type: cmd.type || 'any',
+                description: cmd.description || '',
+                aliases: cmd.aliases || [],
+                categories: cmd.categories || [],
+                hidden: cmd.hidden === true,
+            });
+        }
+    }
+    return { total: items.length, items };
+}
+function serializeModules(framework) {
+    const items = [];
+    const allModules = framework.modules?.getAll();
+    if (allModules) {
+        for (const [name, mod] of allModules) {
+            const modClass = Object.getPrototypeOf(mod)?.constructor;
+            items.push({
+                name,
+                displayName: modClass?.moduleName || name,
+                status: 'loaded',
+                dependencies: Array.from(modClass?.dependencies || []),
+                commandCount: mod.getCommands?.()?.size ?? 0,
+                eventCount: mod.events?.size ?? 0,
+            });
+        }
+    }
+    return { total: items.length, items };
+}
+function serializeServices() {
+    const items = [];
+    try {
+        const entries = ServiceContainer.getAllServiceEntries();
+        for (const entry of entries) {
+            items.push({
+                name: entry.name,
+                singleton: entry.singleton,
+                hasInstance: entry.hasInstance,
+                dependencies: entry.dependencies,
+            });
+        }
+    }
+    catch {
+        // service container not ready
+    }
+    return { total: items.length, items };
+}
+function serializeEvents(framework) {
+    const items = [];
+    const allEvents = framework.events;
+    if (allEvents) {
+        for (const [, evt] of allEvents) {
+            items.push({
+                name: evt.name || 'unknown',
+                source: evt.source || evt.emitter || 'framework',
+            });
+        }
+    }
+    return { total: items.length, items };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zumito-framework",
-  "version": "1.23.3",
+  "version": "1.25.0",
   "description": "Discord.js bot framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",