commandkit 0.1.6 → 0.1.7-dev.20231212150647

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-    <img src="https://raw.githubusercontent.com/underctrl-io/commandkit/master/apps/docs/public/ckit_logo.png" width="60%" />
+    <img src="https://raw.githubusercontent.com/underctrl-io/commandkit/master/apps/docs/public/ckit_logo.svg" width="60%" />
     <br />
     <a href="https://ctrl.lol/discord"><img src="https://img.shields.io/discord/1055188344188973066?color=5865F2&logo=discord&logoColor=white" alt="support server" /></a>
     <a href="https://www.npmjs.com/package/commandkit"><img src="https://img.shields.io/npm/v/commandkit?maxAge=3600" alt="npm version" /></a>
@@ -14,12 +14,12 @@ CommandKit is a library that makes it easy to handle commands and events in your
 
 ## Features
 
--   Very beginner friendly 🚀
--   Support for slash and context menu commands ✅
--   Automatic command registration, edits, and deletion 🤖
--   Supports multiple development servers 🤝
--   Supports multiple users as bot developers 👥
--   Object oriented 💻
+- Beginner friendly 🚀
+- Slash + context menu commands support ✅
+- Multiple dev guilds, users, & roles support 🤝
+- Automatic command updates 🤖
+- REST registration behaviour 📍
+- And much more! 🧪
 
 ## Documentation
 
@@ -99,8 +99,11 @@ new CommandKit({
     // Array of developer role IDs (used for devOnly commands)
     devRoleIds: ['1234567890', '0987654321'],
 
-    // A property that disables CommandKit's built-in validations
+    // Disable CommandKit's built-in validations
     skipBuiltInValidations: true,
+
+    // Update command registration/reload behaviour to register all commands at once
+    bulkRegister: true,
 });
 
 client.login('YOUR_TOKEN_HERE');
@@ -108,4 +111,4 @@ client.login('YOUR_TOKEN_HERE');
 
 ## Support and Suggestions
 
-If you are looking for support or want to provide suggestions, check out the [Discord](https://ctrl.lol/discord).
+Submit any queries or suggestions in our [Discord community](https://ctrl.lol/discord).

package/bin/build.mjs

@@ -0,0 +1,86 @@
+// @ts-check
+
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { build } from 'tsup';
+import { Colors, erase, findCommandKitConfig, panic, write } from './common.mjs';
+import ora from 'ora';
+
+export async function bootstrapProductionBuild(config) {
+    const {
+        sourcemap = false,
+        minify = false,
+        outDir = 'dist',
+        antiCrash = true,
+        src,
+        main,
+    } = await findCommandKitConfig(config);
+
+    const status = ora('Creating optimized production build...\n').start();
+    const start = performance.now();
+
+    erase(outDir);
+
+    try {
+        await build({
+            clean: true,
+            format: ['esm'],
+            dts: false,
+            skipNodeModulesBundle: true,
+            minify,
+            shims: true,
+            banner: {
+                js: '/* Optimized production build generated by CommandKit */',
+            },
+            sourcemap,
+            keepNames: true,
+            outDir,
+            silent: true,
+            entry: [src, '!dist', '!.commandkit', `!${outDir}`],
+        });
+
+        await injectShims(outDir, main, antiCrash);
+
+        status.succeed(
+            Colors.green(`Build completed in ${(performance.now() - start).toFixed(2)}ms!`),
+        );
+        write(
+            Colors.green(
+                `\nRun ${Colors.magenta(`commandkit start`)} ${Colors.green('to start your bot.')}`,
+            ),
+        );
+    } catch (e) {
+        status.fail(`Build failed after ${(performance.now() - start).toFixed(2)}ms!`);
+        panic(e);
+    }
+}
+
+async function injectShims(outDir, main, antiCrash) {
+    const path = join(process.cwd(), outDir, main);
+
+    const antiCrashScript = antiCrash
+        ? [
+              '\n\n// --- CommandKit Anti-Crash Monitor ---',
+              ';(()=>{',
+              "  'use strict';",
+              "  // 'uncaughtException' event is supposed to be used to perform synchronous cleanup before shutting down the process",
+              '  // instead of using it as a means to resume operation.',
+              '  // But it exists here due to compatibility reasons with discord bot ecosystem.',
+              "  const p = (t) => `\\x1b[33m${t}\\x1b[0m`, b = '[CommandKit Anti-Crash Monitor]', l = console.log, e1 = 'uncaughtException', e2 = 'unhandledRejection';",
+              '  if (!process.eventNames().includes(e1)) // skip if it is already handled',
+              '    process.on(e1, (e) => {',
+              '      l(p(`${b} Uncaught Exception`)); l(p(b), p(e.stack || e));',
+              '    })',
+              '  if (!process.eventNames().includes(e2)) // skip if it is already handled',
+              '    process.on(e2, (r) => {',
+              '      l(p(`${b} Unhandled promise rejection`)); l(p(`${b} ${r.stack || r}`));',
+              '    });',
+              '})();',
+              '// --- CommandKit Anti-Crash Monitor ---\n',
+          ].join('\n')
+        : '';
+
+    const finalScript = [antiCrashScript].join('\n');
+
+    return appendFile(path, finalScript);
+}

package/bin/common.mjs

@@ -0,0 +1,102 @@
+// @ts-check
+
+import { rimrafSync } from 'rimraf';
+import { join } from 'node:path';
+import fs from 'node:fs';
+
+const resetColor = '\x1b[0m';
+
+export const Colors = {
+    reset: (text) => `${text}${resetColor}`,
+    bright: (text) => `\x1b[1m${text}${resetColor}`,
+    dim: (text) => `\x1b[2m${text}${resetColor}`,
+    underscore: (text) => `\x1b[4m${text}${resetColor}`,
+    blink: (text) => `\x1b[5m${text}${resetColor}`,
+    reverse: (text) => `\x1b[7m${text}${resetColor}`,
+    hidden: (text) => `\x1b[8m${text}${resetColor}`,
+
+    black: (text) => `\x1b[30m${text}${resetColor}`,
+    red: (text) => `\x1b[31m${text}${resetColor}`,
+    green: (text) => `\x1b[32m${text}${resetColor}`,
+    yellow: (text) => `\x1b[33m${text}${resetColor}`,
+    blue: (text) => `\x1b[34m${text}${resetColor}`,
+    magenta: (text) => `\x1b[35m${text}${resetColor}`,
+    cyan: (text) => `\x1b[36m${text}${resetColor}`,
+    white: (text) => `\x1b[37m${text}${resetColor}`,
+
+    bgBlack: (text) => `\x1b[40m${text}${resetColor}`,
+    bgRed: (text) => `\x1b[41m${text}${resetColor}`,
+    bgGreen: (text) => `\x1b[42m${text}${resetColor}`,
+    bgYellow: (text) => `\x1b[43m${text}${resetColor}`,
+    bgBlue: (text) => `\x1b[44m${text}${resetColor}`,
+    bgMagenta: (text) => `\x1b[45m${text}${resetColor}`,
+    bgCyan: (text) => `\x1b[46m${text}${resetColor}`,
+    bgWhite: (text) => `\x1b[47m${text}${resetColor}`,
+};
+
+export function write(message) {
+    process.stdout.write(message);
+    process.stdout.write('\n');
+}
+
+/**
+ * @returns {never}
+ */
+export function panic(message) {
+    write(Colors.red(`Error: ${message}`));
+    process.exit(1);
+}
+
+export function findPackageJSON() {
+    const cwd = process.cwd();
+    const target = join(cwd, 'package.json');
+
+    if (!fs.existsSync(target)) {
+        panic('Could not find package.json in current directory.');
+    }
+
+    return JSON.parse(fs.readFileSync(target, 'utf8'));
+}
+
+const possibleFileNames = [
+    'commandkit.json',
+    'commandkit.config.json',
+    'commandkit.js',
+    'commandkit.config.js',
+    'commandkit.mjs',
+    'commandkit.config.mjs',
+    'commandkit.cjs',
+    'commandkit.config.cjs',
+];
+
+export async function findCommandKitConfig(src) {
+    const cwd = process.cwd();
+    const locations = src ? [join(cwd, src)] : possibleFileNames.map((name) => join(cwd, name));
+
+    for (const location of locations) {
+        try {
+            return await loadConfigInner(location);
+        } catch (e) {
+            continue;
+        }
+    }
+
+    panic('Could not locate commandkit config.');
+}
+
+async function loadConfigInner(target) {
+    const isJSON = target.endsWith('.json');
+
+    /**
+     * @type {import('..').CommandKitConfig}
+     */
+    const config = await import(`file://${target}`, {
+        assert: isJSON ? { type: 'json' } : undefined,
+    }).then((conf) => conf.default || conf);
+
+    return config;
+}
+
+export function erase(dir) {
+    rimrafSync(dir);
+}

package/bin/development.mjs

@@ -0,0 +1,163 @@
+// @ts-check
+import { config as dotenv } from 'dotenv';
+import { join } from 'node:path';
+import { build } from 'tsup';
+import { Colors, erase, findCommandKitConfig, panic, write } from './common.mjs';
+import { parseEnv } from './parse-env.mjs';
+import child_process from 'node:child_process';
+import ora from 'ora';
+
+const RESTARTING_MSG_PATTERN = /^Restarting '|".+'|"\n?$/;
+const FAILED_RUNNING_PATTERN = /^Failed running '.+'|"\n?$/;
+
+export async function bootstrapDevelopmentServer(opts) {
+    const {
+        src,
+        main,
+        watch = Boolean(opts.noWatch),
+        nodeOptions = [],
+        envExtra = true,
+        clearRestartLogs = true,
+        outDir,
+    } = await findCommandKitConfig(opts.config);
+
+    if (!src) {
+        panic('Could not find src in commandkit.json');
+    }
+
+    if (!main) {
+        panic('Could not find main in commandkit.json');
+    }
+
+    const watchMode = watch;
+    const status = ora(Colors.green('Starting a development server...\n')).start();
+    const start = performance.now();
+
+    if (watchMode && !nodeOptions.includes('--watch')) {
+        nodeOptions.push('--watch');
+    } else if (!watchMode && nodeOptions.includes('--watch')) {
+        nodeOptions.splice(nodeOptions.indexOf('--watch'), 1);
+    }
+
+    if (!nodeOptions.includes('--enable-source-maps')) {
+        nodeOptions.push('--enable-source-maps');
+    }
+
+    erase('.commandkit');
+
+    try {
+        await build({
+            clean: true,
+            format: ['esm'],
+            dts: false,
+            skipNodeModulesBundle: true,
+            minify: false,
+            shims: true,
+            sourcemap: 'inline',
+            keepNames: true,
+            outDir: '.commandkit',
+            silent: true,
+            entry: [src, '!dist', '!.commandkit', `!${outDir}`].filter(Boolean),
+            watch: watchMode,
+        });
+
+        status.succeed(
+            Colors.green(`Dev server started in ${(performance.now() - start).toFixed(2)}ms!\n`),
+        );
+
+        if (watchMode) write(Colors.cyan('Watching for file changes...\n'));
+
+        const processEnv = {};
+
+        const env = dotenv({
+            path: join(process.cwd(), '.env'),
+            // @ts-expect-error
+            processEnv,
+        });
+
+        if (envExtra) {
+            parseEnv(processEnv);
+        }
+
+        if (env.error) {
+            write(Colors.yellow(`[DOTENV] Warning: ${env.error.message}`));
+        }
+
+        if (env.parsed) {
+            write(Colors.blue('[DOTENV] Loaded .env file!'));
+        }
+
+        /**
+         * @type {child_process.ChildProcessWithoutNullStreams}
+         */
+        const ps = child_process.spawn(
+            'node',
+            [...nodeOptions, join(process.cwd(), '.commandkit', main)],
+            {
+                env: {
+                    ...process.env,
+                    ...processEnv,
+                    NODE_ENV: 'development',
+                    // @ts-expect-error
+                    COMMANDKIT_DEV: true,
+                    // @ts-expect-error
+                    COMMANDKIT_PRODUCTION: false,
+                },
+                cwd: process.cwd(),
+            },
+        );
+
+        let isLastLogRestarting = false,
+            hasStarted = false;
+
+        ps.stdout.on('data', (data) => {
+            const message = data.toString();
+
+            if (FAILED_RUNNING_PATTERN.test(message)) {
+                write(Colors.cyan('Failed running the bot, waiting for changes...'));
+                isLastLogRestarting = false;
+                if (!hasStarted) hasStarted = true;
+                return;
+            }
+
+            if (clearRestartLogs && !RESTARTING_MSG_PATTERN.test(message)) {
+                write(message);
+                isLastLogRestarting = false;
+            } else {
+                if (isLastLogRestarting || !hasStarted) {
+                    if (!hasStarted) hasStarted = true;
+                    return;
+                }
+                write(Colors.cyan('⌀ Restarting the bot...'));
+                isLastLogRestarting = true;
+            }
+
+            if (!hasStarted) hasStarted = true;
+        });
+
+        ps.stderr.on('data', (data) => {
+            const message = data.toString();
+
+            if (
+                message.includes(
+                    'ExperimentalWarning: Watch mode is an experimental feature and might change at any time',
+                )
+            )
+                return;
+
+            write(Colors.red(message));
+        });
+
+        ps.on('close', (code) => {
+            write('\n');
+            process.exit(code ?? 0);
+        });
+
+        ps.on('error', (err) => {
+            panic(err);
+        });
+    } catch (e) {
+        status.fail(`Error occurred after ${(performance.now() - start).toFixed(2)}ms!\n`);
+        panic(e.stack ?? e);
+    }
+}

package/bin/index.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+// @ts-check
+
+import { Command } from 'commander';
+import { bootstrapDevelopmentServer } from './development.mjs';
+import { bootstrapProductionServer } from './production.mjs';
+import { bootstrapProductionBuild } from './build.mjs';
+
+const program = new Command('commandkit');
+
+program
+    .command('dev')
+    .description('Start your bot in development mode.')
+    .option('-c, --config <path>', 'Path to your commandkit config file.', './commandkit.js')
+    .action(() => {
+        const options = program.opts();
+        bootstrapDevelopmentServer(options);
+    });
+
+program
+    .command('start')
+    .description('Start your bot in production mode after running the build command.')
+    .option('-c, --config <path>', 'Path to your commandkit.json file.', './commandkit.js')
+    .action(() => {
+        const options = program.opts();
+        bootstrapProductionServer(options.config);
+    });
+
+program
+    .command('build')
+    .description('Build your project for production usage.')
+    .option('-c, --config <path>', 'Path to your commandkit.json file.', './commandkit.json')
+    .action(() => {
+        const options = program.opts();
+        bootstrapProductionBuild(options.config);
+    });
+
+program.parse();

package/bin/parse-env.mjs

@@ -0,0 +1,61 @@
+// @ts-check
+
+import { randomUUID } from 'node:crypto';
+
+const valuesMap = {
+    true: true,
+    false: false,
+    null: null,
+    undefined: undefined,
+    __UUIDv4__: () => randomUUID(),
+};
+
+const VALUE_PREFIXES = {
+    JSON: 'JSON::',
+    DATE: 'DATE::',
+};
+
+function catcher(fn) {
+    try {
+        fn();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function parseEnv(src) {
+    for (const key in src) {
+        const value = src[key];
+
+        if (typeof value !== 'string') continue;
+
+        if (value.startsWith(VALUE_PREFIXES.JSON)) {
+            catcher(() => (src[key] = JSON.parse(value.replace(VALUE_PREFIXES.JSON, ''))));
+            continue;
+        }
+
+        if (value.startsWith(VALUE_PREFIXES.DATE)) {
+            src[key] = new Date(value.replace(VALUE_PREFIXES.DATE, ''));
+            continue;
+        }
+
+        if (value.includes(',')) {
+            src[key] = value.split(',').map((v) => v.trim());
+            continue;
+        }
+
+        if (/^[0-9]+n$/.test(value)) {
+            src[key] = BigInt(value);
+            continue;
+        }
+
+        if (value in valuesMap) {
+            src[key] =
+                typeof valuesMap[value] === 'function' ? valuesMap[value]() : valuesMap[value];
+            continue;
+        }
+    }
+
+    return src;
+}

package/bin/production.mjs

@@ -0,0 +1,83 @@
+// @ts-check
+import { config as dotenv } from 'dotenv';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { Colors, findCommandKitConfig, panic, write } from './common.mjs';
+import { parseEnv } from './parse-env.mjs';
+import child_process from 'node:child_process';
+
+export async function bootstrapProductionServer(config) {
+    const {
+        main,
+        outDir = 'dist',
+        envExtra = true,
+        sourcemap,
+    } = await findCommandKitConfig(config);
+
+    if (!existsSync(join(process.cwd(), outDir, main))) {
+        panic('Could not find production build, maybe run `commandkit build` first?');
+    }
+
+    try {
+        const processEnv = {};
+
+        const env = dotenv({
+            path: join(process.cwd(), '.env'),
+            // @ts-expect-error
+            processEnv,
+        });
+
+        if (envExtra) {
+            parseEnv(processEnv);
+        }
+
+        if (env.error) {
+            write(Colors.yellow(`[DOTENV] Warning: ${env.error.message}`));
+        }
+
+        if (env.parsed) {
+            write(Colors.blue('[DOTENV] Loaded .env file!'));
+        }
+
+        /**
+         * @type {child_process.ChildProcessWithoutNullStreams}
+         */
+        const ps = child_process.spawn(
+            'node',
+            [sourcemap ? '--enable-source-maps' : '', join(process.cwd(), outDir, main)].filter(
+                Boolean,
+            ),
+            {
+                env: {
+                    ...process.env,
+                    ...processEnv,
+                    NODE_ENV: 'production',
+                    // @ts-expect-error
+                    COMMANDKIT_DEV: false,
+                    //  @ts-expect-error
+                    COMMANDKIT_PROD: true,
+                },
+                cwd: process.cwd(),
+            },
+        );
+
+        ps.stdout.on('data', (data) => {
+            write(data.toString());
+        });
+
+        ps.stderr.on('data', (data) => {
+            write(Colors.red(data.toString()));
+        });
+
+        ps.on('close', (code) => {
+            write('\n');
+            process.exit(code ?? 0);
+        });
+
+        ps.on('error', (err) => {
+            panic(err);
+        });
+    } catch (e) {
+        panic(e);
+    }
+}