lumisjs 1.0.0

package/src/dashboard/DashboardManager.js

@@ -0,0 +1,362 @@
+'use strict';
+
+const http = require('http');
+const { URL } = require('url');
+const helmet = require('helmet');
+
+/**
+ * Built-in Dashboard & Analytics API.
+ * Provides an HTTP REST API + real-time metrics for monitoring your bot.
+ * 
+ * @example
+ * const client = new Client({
+ *   dashboard: { enabled: true, port: 3000, auth: 'my-secret-key' }
+ * });
+ * // GET /api/stats
+ * // GET /api/guilds
+ * // GET /api/commands
+ * // GET /api/health
+ * // GET /api/cache
+ * // GET /api/plugins
+ * // GET /api/services
+ * // GET /api/middleware
+ */
+class DashboardManager {
+  constructor(client, options = {}) {
+    this.client = client;
+    this.options = {
+      enabled: options.enabled || false,
+      port: options.port || 3000,
+      host: options.host || '0.0.0.0',
+      auth: options.auth || null,
+      cors: options.cors !== false,
+      ...options,
+    };
+
+    /** @type {http.Server|null} */
+    this._server = null;
+
+    /** @type {Map<string, number>} Command usage counters */
+    this._commandUsage = new Map();
+
+    /** @type {Array} Recent errors */
+    this._recentErrors = [];
+
+    /** @type {number} */
+    this._requestCount = 0;
+
+    /** @type {Map<string, Function>} Custom API routes */
+    this._customRoutes = new Map();
+
+    // Track command usage
+    this._trackUsage();
+
+    // Auto-start if enabled
+    if (this.options.enabled) {
+      this.client.on?.('ready', () => this.start());
+    }
+  }
+
+  /**
+   * Start the dashboard HTTP server.
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this._server) return;
+
+    this._server = http.createServer((req, res) => {
+      this._handleRequest(req, res);
+    });
+
+    return new Promise((resolve, reject) => {
+      this._server.listen(this.options.port, this.options.host, () => {
+        this.client.logger?.info(`📊 Dashboard running at http://localhost:${this.options.port}`);
+        resolve();
+      });
+
+      this._server.on('error', (err) => {
+        this.client.logger?.error('Dashboard server error:', err.message);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Stop the dashboard server.
+   */
+  async stop() {
+    if (!this._server) return;
+    return new Promise((resolve) => {
+      this._server.close(() => {
+        this._server = null;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Register a custom API route.
+   * @param {string} path - e.g. '/api/custom'
+   * @param {Function} handler - (req, res, client) => void
+   */
+  route(path, handler) {
+    this._customRoutes.set(path, handler);
+    return this;
+  }
+
+  /** @private */
+  _handleRequest(req, res) {
+    this._requestCount++;
+
+    // Apply Helmet security headers
+    helmet({
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          scriptSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+          imgSrc: ["'self'", "data:", "https:"],
+        },
+      },
+    })(req, res, () => {});
+
+    // CORS
+    if (this.options.cors) {
+      res.setHeader('Access-Control-Allow-Origin', this.options.corsOrigin || '*');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+      res.setHeader('Access-Control-Allow-Credentials', 'true');
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+    }
+
+    // Auth
+    if (this.options.auth) {
+      const authHeader = req.headers.authorization;
+      if (!authHeader || authHeader !== `Bearer ${this.options.auth}`) {
+        this._json(res, 401, { error: 'Unauthorized' });
+        return;
+      }
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+
+    // Custom routes first
+    if (this._customRoutes.has(pathname)) {
+      try {
+        this._customRoutes.get(pathname)(req, res, this.client);
+      } catch (err) {
+        this._json(res, 500, { error: err.message });
+      }
+      return;
+    }
+
+    // Built-in routes
+    switch (pathname) {
+      case '/api/stats':
+        return this._routeStats(res);
+      case '/api/guilds':
+        return this._routeGuilds(res);
+      case '/api/commands':
+        return this._routeCommands(res);
+      case '/api/health':
+        return this._routeHealth(res);
+      case '/api/cache':
+        return this._routeCache(res);
+      case '/api/plugins':
+        return this._routePlugins(res);
+      case '/api/services':
+        return this._routeServices(res);
+      case '/api/middleware':
+        return this._routeMiddleware(res);
+      case '/api/errors':
+        return this._routeErrors(res);
+      default:
+        this._json(res, 404, { error: 'Not Found', availableRoutes: [
+          '/api/stats', '/api/guilds', '/api/commands', '/api/health',
+          '/api/cache', '/api/plugins', '/api/services', '/api/middleware',
+          '/api/errors',
+        ]});
+    }
+  }
+
+  /** @private */
+  _routeStats(res) {
+    const memUsage = process.memoryUsage();
+
+    this._json(res, 200, {
+      bot: {
+        user: this.client.user ? {
+          id: this.client.user.id,
+          tag: this.client.user.tag,
+          avatar: this.client.user.avatar,
+        } : null,
+        uptime: this.client.uptime,
+        uptimeFormatted: this._formatUptime(this.client.uptime),
+        ping: this.client.ping,
+        ready: this.client.ready,
+        readyAt: this.client.readyAt,
+      },
+      counts: {
+        guilds: this.client.guilds?.size || 0,
+        channels: this.client.channels?.size || 0,
+        users: this.client.users?.size || 0,
+        commands: this.client.commands?.commands?.size || 0,
+      },
+      memory: {
+        rss: Math.round(memUsage.rss / 1024 / 1024) + 'MB',
+        heapUsed: Math.round(memUsage.heapUsed / 1024 / 1024) + 'MB',
+        heapTotal: Math.round(memUsage.heapTotal / 1024 / 1024) + 'MB',
+      },
+      system: {
+        nodeVersion: process.version,
+        platform: process.platform,
+        pid: process.pid,
+      },
+      shard: this.client.shard || null,
+      dashboard: {
+        requests: this._requestCount,
+      }
+    });
+  }
+
+  /** @private */
+  _routeGuilds(res) {
+    const guilds = [];
+    if (this.client.guilds) {
+      for (const [id, guild] of this.client.guilds) {
+        guilds.push({
+          id,
+          name: guild.name,
+          memberCount: guild.memberCount,
+          icon: guild.icon,
+          ownerId: guild.ownerId,
+        });
+      }
+    }
+    this._json(res, 200, { total: guilds.length, guilds });
+  }
+
+  /** @private */
+  _routeCommands(res) {
+    const commands = [];
+    if (this.client.commands?.commands) {
+      for (const [name, cmd] of this.client.commands.commands) {
+        commands.push({
+          name,
+          description: cmd.description || '',
+          cooldown: cmd.cooldown || 0,
+          guards: cmd.guards?.map(g => g.name) || [],
+          usage: this._commandUsage.get(name) || 0,
+        });
+      }
+    }
+    this._json(res, 200, { total: commands.length, commands });
+  }
+
+  /** @private */
+  _routeHealth(res) {
+    const healthy = this.client.ready && this.client.ws?.connected !== false;
+    this._json(res, healthy ? 200 : 503, {
+      status: healthy ? 'healthy' : 'unhealthy',
+      ready: this.client.ready,
+      uptime: this.client.uptime,
+      ping: this.client.ping,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /** @private */
+  _routeCache(res) {
+    this._json(res, 200, {
+      guilds: this.client.guilds?.size || 0,
+      channels: this.client.channels?.size || 0,
+      users: this.client.users?.size || 0,
+      adapter: this.client.cache?.adapter?.constructor?.name || 'unknown',
+    });
+  }
+
+  /** @private */
+  _routePlugins(res) {
+    const plugins = this.client.plugins?.list?.() || [];
+    this._json(res, 200, { total: plugins.length, plugins });
+  }
+
+  /** @private */
+  _routeServices(res) {
+    const services = this.client.services?.list?.() || [];
+    this._json(res, 200, { total: services.length, services });
+  }
+
+  /** @private */
+  _routeMiddleware(res) {
+    const stats = this.client.middleware?.stats || { global: 0, command: 0, group: 0, total: 0 };
+    this._json(res, 200, stats);
+  }
+
+  /** @private */
+  _routeErrors(res) {
+    this._json(res, 200, { 
+      total: this._recentErrors.length, 
+      errors: this._recentErrors.slice(-50)
+    });
+  }
+
+  /** @private */
+  _trackUsage() {
+    this.client.on?.('interactionCreate', (interaction) => {
+      if (interaction?.commandName) {
+        const current = this._commandUsage.get(interaction.commandName) || 0;
+        this._commandUsage.set(interaction.commandName, current + 1);
+      }
+    });
+
+    this.client.on?.('error', (error) => {
+      this._recentErrors.push({
+        message: error?.message || String(error),
+        timestamp: new Date().toISOString(),
+      });
+      if (this._recentErrors.length > 100) {
+        this._recentErrors = this._recentErrors.slice(-100);
+      }
+    });
+  }
+
+  /** @private */
+  _json(res, status, data) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data, null, 2));
+  }
+
+  /** @private */
+  _formatUptime(ms) {
+    if (!ms) return '0s';
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+
+    const parts = [];
+    if (days > 0) parts.push(`${days}d`);
+    if (hours % 24 > 0) parts.push(`${hours % 24}h`);
+    if (minutes % 60 > 0) parts.push(`${minutes % 60}m`);
+    if (seconds % 60 > 0) parts.push(`${seconds % 60}s`);
+    return parts.join(' ') || '0s';
+  }
+
+  /**
+   * Destroy the dashboard.
+   */
+  async destroy() {
+    await this.stop();
+    this._commandUsage.clear();
+    this._recentErrors = [];
+    this._customRoutes.clear();
+  }
+}
+
+module.exports = DashboardManager;

package/src/datagen/DataGenerator.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { SchemaGenerator } = require('./schema/SchemaGenerator');
+
+class DataGenerator {
+  /**
+   * @param {object} options
+   * @param {object} options.schema - JSON Schema definition
+   * @param {string|number} [options.seed] - Optional seed for reproducible output
+   * @param {string} [options.locale='en'] - Locale hint for faker
+   * @param {object} [options.pluginManager] - Optional plugin manager
+   * @param {number} [options.count=1] - Default number of records to generate
+   */
+  constructor({ schema, seed, locale = 'en', pluginManager, count = 1 } = {}) {
+    if (!schema) throw new TypeError('schema is required');
+    this.schema = schema;
+    this.seed = seed;
+    this.locale = locale;
+    this.pluginManager = pluginManager;
+    this.count = count;
+
+    this._generator = new SchemaGenerator({ schema, seed, locale, pluginManager });
+  }
+
+  /**
+   * Generate a single record.
+   * @returns {any}
+   */
+  generate() {
+    return this._generator.generate();
+  }
+
+  /**
+   * Generate multiple records.
+   * @param {number} [count] - Overrides instance count if provided
+   * @returns {any[]}
+   */
+  generateMany(count) {
+    const n = count ?? this.count;
+    if (typeof n !== 'number' || n < 1 || !Number.isInteger(n)) {
+      throw new RangeError('count must be a positive integer');
+    }
+    return Array.from({ length: n }, () => this._generator.generate());
+  }
+}
+
+module.exports = { DataGenerator };

package/src/datagen/apis/GraphqlMocker.js

@@ -0,0 +1,16 @@
+'use strict';
+
+/**
+ * Minimal GraphQL mock API helper.
+ *
+ * TODO: hook into graphql-js and generate resolvers based on schema definitions.
+ */
+
+function mockFromGraphqlSchema(schema, options = {}) {
+  return {
+    schema,
+    mocks: {},
+  };
+}
+
+module.exports = { mockFromGraphqlSchema };

package/src/datagen/apis/OpenApiMocker.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Minimal OpenAPI mocker helper.
+ *
+ * TODO: implement full OpenAPI parsing + mock data generation.
+ */
+
+function mockFromOpenApi(openApiSpec, options = {}) {
+  // Placeholder: Walk through the OpenAPI paths and generate responses for each operation.
+  // Real implementation should support request/response schemas, security, and status codes.
+  return {
+    info: openApiSpec.info,
+    paths: {},
+  };
+}
+
+module.exports = { mockFromOpenApi };

package/src/datagen/cli.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { DataGenerator } = require('./DataGenerator');
+const { loadSchema } = require('./schema/loadSchema');
+const { formatters } = require('./formatters');
+const { PluginManager } = require('./plugin/PluginManager');
+
+function parseArgs(argv) {
+  const args = {};
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i += 2;
+      } else {
+        args[key] = true;
+        i += 1;
+      }
+    } else {
+      // positional
+      if (!args._) args._ = [];
+      args._.push(arg);
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function showHelp() {
+  console.log(`
+lumis-datagen — schema-based mock data generator
+
+Usage:
+  lumis-datagen --schema schema.json --count 1000 --out out.json [options]
+
+Options:
+  --schema <file>        JSON schema file (required)
+  --count <n>            Number of records to generate (default: 1)
+  --out <file>           Output file path (default: stdout)
+  --format <fmt>         Output format: json|csv|sql|mongo (default: json)
+  --seed <value>         Deterministic seed for repeatable data
+  --locale <locale>      Locale for locale-aware generators (default: en)
+  --plugin-dir <dir>     Path to load plugins from
+  --batch <size>         Batch size for streaming output
+  --help                 Show this help message
+`);
+}
+
+function ensureExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+}
+
+function runCli({ argv, cwd, rootDir }) {
+  const opts = parseArgs(argv);
+  if (opts.help || opts.h) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const schemaPath = opts.schema || opts.s;
+  if (!schemaPath) {
+    console.error('Error: --schema is required');
+    showHelp();
+    process.exit(1);
+  }
+
+  const schemaFile = path.isAbsolute(schemaPath) ? schemaPath : path.join(cwd, schemaPath);
+  ensureExists(schemaFile);
+
+  const count = Number(opts.count || opts.c || 1);
+  const outPath = opts.out || opts.o;
+  const format = (opts.format || 'json').toLowerCase();
+  const seed = opts.seed || opts._seed || undefined;
+  const locale = opts.locale || 'en';
+  const pluginDir = opts['plugin-dir'] || opts.p || null;
+  const batchSize = Number(opts.batch || 0);
+
+  const schema = loadSchema(schemaFile);
+  const pluginManager = new PluginManager({ pluginDir, rootDir, locale });
+
+  const generator = new DataGenerator({ schema, seed, locale, pluginManager });
+  const outputFormatter = formatters[format];
+  if (!outputFormatter) {
+    console.error(`Unknown format: ${format}`);
+    process.exit(1);
+  }
+
+  const stream = outputFormatter(streamGenerator(generator, count, batchSize), { schema, count, locale });
+
+  if (outPath) {
+    const outFile = path.isAbsolute(outPath) ? outPath : path.join(cwd, outPath);
+    const writeStream = fs.createWriteStream(outFile, { encoding: 'utf8' });
+    stream.pipe(writeStream);
+    writeStream.on('finish', () => {
+      console.log(`✅ Generated ${count} record(s) to ${outFile}`);
+    });
+  } else {
+    stream.pipe(process.stdout);
+  }
+}
+
+function* streamGenerator(generator, count, batchSize) {
+  if (!batchSize || batchSize < 1) {
+    for (let i = 0; i < count; i += 1) {
+      yield generator.generate();
+    }
+    return;
+  }
+
+  let remaining = count;
+  while (remaining > 0) {
+    const currentBatch = Math.min(batchSize, remaining);
+    const records = [];
+    for (let i = 0; i < currentBatch; i += 1) {
+      records.push(generator.generate());
+    }
+    yield records;
+    remaining -= currentBatch;
+  }
+}
+
+module.exports = { runCli };

package/src/datagen/formatters/csv.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const { Readable } = require('stream');
+
+function CsvFormatter(generator, { schema }) {
+  const stream = new Readable({ objectMode: true, read() {} });
+  const fields = Object.keys(schema.properties || {});
+  let headerWritten = false;
+
+  const toCsv = (record) => {
+    return fields
+      .map((key) => {
+        let value = record[key];
+        if (value === undefined || value === null) return '';
+        const str = String(value);
+        // escape "
+        const escaped = str.replace(/"/g, '""');
+        if (escaped.includes(',') || escaped.includes('"') || escaped.includes('\n')) {
+          return `"${escaped}"`;
+        }
+        return escaped;
+      })
+      .join(',');
+  };
+
+  stream._read = function () {
+    if (!headerWritten) {
+      this.push(fields.join(',') + '\n');
+      headerWritten = true;
+      return;
+    }
+
+    const { value, done } = generator.next ? generator.next() : { done: true };
+    if (done) {
+      this.push(null);
+      return;
+    }
+
+    this.push(toCsv(value) + '\n');
+  };
+
+  return stream;
+}
+
+module.exports = { CsvFormatter };

package/src/datagen/formatters/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const { JsonFormatter } = require('./json');
+const { CsvFormatter } = require('./csv');
+const { SqlFormatter } = require('./sql');
+const { MongoFormatter } = require('./mongo');
+
+const formatters = {
+  json: JsonFormatter,
+  csv: CsvFormatter,
+  sql: SqlFormatter,
+  mongo: MongoFormatter,
+};
+
+module.exports = { formatters };

package/src/datagen/formatters/json.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const { Readable } = require('stream');
+
+function JsonFormatter(generator, { count }) {
+  const stream = new Readable({ objectMode: true, read() {} });
+  let wroteHeader = false;
+  stream._read = function () {
+    if (!wroteHeader) {
+      this.push('[');
+      wroteHeader = true;
+    }
+
+    const { value, done } = generator.next ? generator.next() : { done: true };
+    if (done) {
+      this.push(']');
+      this.push(null);
+      return;
+    }
+
+    const json = JSON.stringify(value, null, 2);
+    if (this._firstRecord) {
+      this._firstRecord = false;
+      this.push(`\n${json}`);
+    } else {
+      this.push(`,\n${json}`);
+    }
+  };
+  stream._firstRecord = true;
+  return stream;
+}
+
+module.exports = { JsonFormatter };

package/src/datagen/formatters/mongo.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const { Readable } = require('stream');
+
+function MongoFormatter(generator, { schema }) {
+  const collection = schema.collection || 'data';
+  const stream = new Readable({ objectMode: true, read() {} });
+
+  stream._read = function () {
+    const { value, done } = generator.next ? generator.next() : { done: true };
+    if (done) {
+      this.push(null);
+      return;
+    }
+
+    this.push(`db.getCollection('${collection}').insertOne(${JSON.stringify(value, null, 2)});\n`);
+  };
+
+  return stream;
+}
+
+module.exports = { MongoFormatter };