meocord 4.0.0-beta.1 → 4.0.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # meocord
 
+## 4.0.0-beta.2
+
+### Major Changes
+
+- [#36](https://github.com/l7aromeo/meocord/pull/36) [`45e564e`](https://github.com/l7aromeo/meocord/commit/45e564e6baff17313037372ec56baa1711a3584c) Thanks [@l7aromeo](https://github.com/l7aromeo)! - **Breaking:** `app.start()` rejects when the login fails. It logged the error and resolved, so a bot
+  with an invalid token went on to log "Application started" and exit with code 0, which Docker's
+  `restart: on-failure`, systemd and CI all read as success. New applications' `main.ts` sets
+  `process.exitCode = 1` when startup fails; add the same to an existing entry point's `catch`. See the
+  [migration guide](https://github.com/l7aromeo/meocord/blob/main/docs/MIGRATING.md#4-build-and-start).
+
+### Patch Changes
+
+- [#37](https://github.com/l7aromeo/meocord/pull/37) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Type the CommonJS build as CommonJS. Every entry point's `require` condition resolved to the ESM
+  declarations, so a CommonJS TypeScript project was told `meocord/core` is an ES module it cannot
+  `require`, even with `skipLibCheck`. Each entry now ships `.d.cts` declarations for `require`, and
+  `meocord/eslint` types its `module.exports` array as what `require` returns.
+
+- [#35](https://github.com/l7aromeo/meocord/pull/35) [`b93a771`](https://github.com/l7aromeo/meocord/commit/b93a771b19664345fec4222d5a2c29dcf5b31a0d) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Generate code that passes a new application's own `lint`. A generated guard failed `tsc` and ESLint
+  — `GuardInterface` imported as a value, and an unused `context` parameter — and generated message and
+  reaction controllers imported names they never used, which only the application's ESLint, run in the
+  background after generating, removed. New applications also typecheck `meocord.config.ts`: the
+  template's `tsconfig.json` includes it instead of excluding it, so a type error in the config fails
+  `lint`, and editors resolve `paths` aliases imported there. `noEmit` stays on, so `tsc` writes nothing
+  beside it.
+
 ## 4.0.0-beta.1
 
 ### Major Changes

package/dist/cjs/core/index.cjs

@@ -106,28 +106,30 @@ class MeoCordApp {
         }
         return this.controllerInstancesCache.get(controllerClass);
     }
-    async start() {
-        try {
-            this.logger.log('Starting bot...');
-            this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
-                    this.activityInterval = setInterval(()=>this.updateActivity(), 10000);
-                    await this.registerCommands();
-                }));
-            this.bot.on('interactionCreate', (interaction)=>this.runListener('interactionCreate', ()=>this.handleInteraction(interaction)));
-            this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.handleMessage(message)));
-            this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.handleReaction(reaction, {
-                        user,
-                        action: enum_index.ReactionHandlerAction.ADD
-                    })));
-            this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
-                        user,
-                        action: enum_index.ReactionHandlerAction.REMOVE
-                    })));
-            await this.bot.login(this.discordToken);
-            this.logger.log('Bot is online!');
-        } catch (error) {
-            this.logger.error('Error during bot startup:', error);
-        }
+    /**
+   * Registers the Discord event handlers and logs in.
+   *
+   * Rejects when the login fails -- an invalid token, or Discord unreachable -- so the caller can
+   * stop with a non-zero exit code. A bot that never came online is a failed start, and a
+   * supervisor such as Docker's `restart: on-failure` or systemd can only tell if the process says so.
+   */ async start() {
+        this.logger.log('Starting bot...');
+        this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
+                this.activityInterval = setInterval(()=>this.updateActivity(), 10000);
+                await this.registerCommands();
+            }));
+        this.bot.on('interactionCreate', (interaction)=>this.runListener('interactionCreate', ()=>this.handleInteraction(interaction)));
+        this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.handleMessage(message)));
+        this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.handleReaction(reaction, {
+                    user,
+                    action: enum_index.ReactionHandlerAction.ADD
+                })));
+        this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
+                    user,
+                    action: enum_index.ReactionHandlerAction.REMOVE
+                })));
+        await this.bot.login(this.discordToken);
+        this.logger.log('Bot is online!');
     }
     async registerCommands() {
         // Keyed by type and name together, because that pair is what Discord treats as one

package/dist/esm/bin/app-template/src/main.ts.template

@@ -11,4 +11,8 @@ async function bootstrap() {
   logger.log('Application started')
 }
 
-bootstrap().catch(error => logger.error('Error during startup:', error))
+bootstrap().catch(error => {
+  logger.error('Error during startup:', error)
+  // A bot that never came online is a failed start: exit non-zero, so Docker, systemd or CI see it.
+  process.exitCode = 1
+})

package/dist/esm/bin/app-template/tsconfig.json.template

@@ -25,6 +25,6 @@
     },
     "types": ["node"]
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["meocord.config.ts", "dist", "vitest.config.ts", "node_modules", "src/**/*.spec.ts"]
+  "include": ["src/**/*.ts", "meocord.config.ts"],
+  "exclude": ["dist", "vitest.config.ts", "node_modules", "src/**/*.spec.ts"]
 }

package/dist/esm/bin/builder-template/controller/message.controller.template

@@ -1,5 +1,5 @@
-import { MessageHandler, Controller, Command } from 'meocord/decorator'
-import { EmbedBuilder, Message } from 'discord.js'
+import { MessageHandler, Controller } from 'meocord/decorator'
+import { Message } from 'discord.js'
 import { Logger } from 'meocord/common'
 
 @Controller()

package/dist/esm/bin/builder-template/controller/reaction.controller.template

@@ -1,7 +1,7 @@
-import { MessageReaction, User } from 'discord.js'
+import { MessageReaction } from 'discord.js'
 import { Controller, ReactionHandler } from 'meocord/decorator'
 import { Logger } from 'meocord/common'
-import { CommandType, ReactionHandlerAction } from 'meocord/enum'
+import { ReactionHandlerAction } from 'meocord/enum'
 import { type ReactionHandlerOptions } from 'meocord/interface'
 
 @Controller()
@@ -10,12 +10,12 @@ export class {{className}}ReactionController {
 
   @ReactionHandler('😋')
   async handleReaction(reaction: MessageReaction, { user, action }: ReactionHandlerOptions) {
-    this.logger.log(`Reaction 😋 ${action === ReactionHandlerAction.ADD ? 'added' : 'removed'}.`);
+    this.logger.log(`Reaction 😋 ${action === ReactionHandlerAction.ADD ? 'added' : 'removed'}.`)
 
-    if (!reaction.message) return;
+    if (!reaction.message) return
 
     if (action === ReactionHandlerAction.ADD) {
-      await reaction.message.reply(`${user.username} reacted with 😋!`);
+      await reaction.message.reply(`${user.username} reacted with 😋!`)
     }
   }
 

package/dist/esm/bin/builder-template/guard.template

@@ -1,10 +1,10 @@
 import { Guard } from 'meocord/decorator'
-import { GuardInterface } from 'meocord/interface'
+import { type GuardInterface } from 'meocord/interface'
 import { BaseInteraction, Message, MessageReaction } from 'discord.js'
 
 @Guard()
 export class {{className}}Guard implements GuardInterface {
-  async canActivate(context: BaseInteraction | Message | MessageReaction): Promise<boolean> {
+  async canActivate(_context: BaseInteraction | Message | MessageReaction): Promise<boolean> {
     // TODO: Implement the guard logic to determine if the interaction is allowed
     return true
   }

package/dist/esm/core/meocord.app.js

@@ -88,28 +88,30 @@ class MeoCordApp {
         }
         return this.controllerInstancesCache.get(controllerClass);
     }
-    async start() {
-        try {
-            this.logger.log('Starting bot...');
-            this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
-                    this.activityInterval = setInterval(()=>this.updateActivity(), 10000);
-                    await this.registerCommands();
-                }));
-            this.bot.on('interactionCreate', (interaction)=>this.runListener('interactionCreate', ()=>this.handleInteraction(interaction)));
-            this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.handleMessage(message)));
-            this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.handleReaction(reaction, {
-                        user,
-                        action: ReactionHandlerAction.ADD
-                    })));
-            this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
-                        user,
-                        action: ReactionHandlerAction.REMOVE
-                    })));
-            await this.bot.login(this.discordToken);
-            this.logger.log('Bot is online!');
-        } catch (error) {
-            this.logger.error('Error during bot startup:', error);
-        }
+    /**
+   * Registers the Discord event handlers and logs in.
+   *
+   * Rejects when the login fails -- an invalid token, or Discord unreachable -- so the caller can
+   * stop with a non-zero exit code. A bot that never came online is a failed start, and a
+   * supervisor such as Docker's `restart: on-failure` or systemd can only tell if the process says so.
+   */ async start() {
+        this.logger.log('Starting bot...');
+        this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
+                this.activityInterval = setInterval(()=>this.updateActivity(), 10000);
+                await this.registerCommands();
+            }));
+        this.bot.on('interactionCreate', (interaction)=>this.runListener('interactionCreate', ()=>this.handleInteraction(interaction)));
+        this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.handleMessage(message)));
+        this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.handleReaction(reaction, {
+                    user,
+                    action: ReactionHandlerAction.ADD
+                })));
+        this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
+                    user,
+                    action: ReactionHandlerAction.REMOVE
+                })));
+        await this.bot.login(this.discordToken);
+        this.logger.log('Bot is online!');
     }
     async registerCommands() {
         // Keyed by type and name together, because that pair is what Discord treats as one

package/dist/esm/package.json.js

@@ -1,4 +1,4 @@
-var version = "4.0.0-beta.1";
+var version = "4.0.0-beta.2";
 var packageJson = {
 	version: version};
 

package/dist/types/common/index.d.cts

@@ -0,0 +1,53 @@
+import { ColorResolvable } from 'discord.js';
+
+declare class Logger {
+    private context?;
+    private readonly colorMap;
+    constructor(context?: string | undefined);
+    log(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    error(...args: any[]): void;
+    debug(...args: any[]): void;
+    verbose(...args: any[]): void;
+    private formatMessage;
+    private logWithContext;
+}
+
+declare class Theme {
+    static successColor: ColorResolvable;
+    static infoColor: ColorResolvable;
+    static errorColor: ColorResolvable;
+    static warningColor: ColorResolvable;
+}
+
+/**
+ * Composes multiple class or method decorators into a single decorator.
+ *
+ * @example
+ * ```typescript
+ * export const Protected = () => applyDecorators(
+ *   UseGuard(DefaultGuard, GlobalRateLimiterGuard),
+ * )
+ *
+ * @Controller()
+ * @Protected()
+ * export class PingController {}
+ * ```
+ */
+declare function applyDecorators(...decorators: (ClassDecorator | MethodDecorator)[]): ClassDecorator & MethodDecorator;
+/**
+ * Attaches arbitrary metadata to a class or method. Use alongside `Reflect.getMetadata` to read it back.
+ *
+ * @example
+ * ```typescript
+ * export const Roles = (...roles: string[]) => SetMetadata('roles', roles)
+ *
+ * @Command('admin', CommandType.SLASH)
+ * @Roles('admin', 'moderator')
+ * async adminCommand(interaction: ChatInputCommandInteraction) {}
+ * ```
+ */
+declare function SetMetadata<V = any>(metadataKey: string, metadataValue: V): ClassDecorator & MethodDecorator;
+
+export { Logger, SetMetadata, Theme, applyDecorators };

package/dist/types/controller.enum-DYfhYaat.d.cts

@@ -0,0 +1,36 @@
+/**
+ * The kinds of interaction a `@Command` method can be bound to.
+ *
+ * Each member names one Discord interaction shape rather than a family of them, so a
+ * handler's parameter type follows from its command type alone. That is why the four
+ * entity select menus are separate members instead of one `SELECT_MENU`: Discord sends
+ * them as distinct component types (5-8) carrying different resolved data, and
+ * collapsing them would leave the handler with a union it has to re-narrow by hand.
+ */
+declare enum CommandType {
+    /** Chat input command, or one subcommand of it. */
+    SLASH = "SLASH",
+    /** User or message context menu command. */
+    CONTEXT_MENU = "CONTEXT_MENU",
+    /** Activity launch command (`ApplicationCommandType.PrimaryEntryPoint`). */
+    PRIMARY_ENTRY_POINT = "PRIMARY_ENTRY_POINT",
+    BUTTON = "BUTTON",
+    /** String select menu — the one whose options the application defines itself. */
+    SELECT_MENU = "SELECT_MENU",
+    USER_SELECT_MENU = "USER_SELECT_MENU",
+    ROLE_SELECT_MENU = "ROLE_SELECT_MENU",
+    MENTIONABLE_SELECT_MENU = "MENTIONABLE_SELECT_MENU",
+    CHANNEL_SELECT_MENU = "CHANNEL_SELECT_MENU",
+    MODAL_SUBMIT = "MODAL_SUBMIT"
+}
+/**
+ * Enum representing actions that can be performed on a message reaction.
+ */
+declare enum ReactionHandlerAction {
+    /** Reaction added to a message. */
+    ADD = "ADD",
+    /** Reaction removed from a message. */
+    REMOVE = "REMOVE"
+}
+
+export { CommandType as C, ReactionHandlerAction as R };

package/dist/types/core/index.d.cts

@@ -0,0 +1,131 @@
+import { Container, ServiceIdentifier } from 'inversify';
+import { Client, ActivityOptions } from 'discord.js';
+
+declare class MeoCordApp {
+    private readonly controllerClasses;
+    private readonly container;
+    private readonly discordClient;
+    private discordToken;
+    private activities?;
+    private readonly logger;
+    private readonly bot;
+    private isShuttingDown;
+    private activityInterval;
+    private controllerInstancesCache;
+    constructor(controllerClasses: (new (...args: any[]) => any)[], container: Container, discordClient: Client, discordToken: string, activities?: ActivityOptions[] | undefined);
+    /**
+     * Runs an event handler so a failure inside it cannot take the process down.
+     *
+     * discord.js calls listeners without awaiting them, so a rejection escaping one has
+     * nothing left to settle it: Node reports an unhandled rejection, which terminates
+     * the process by default. Losing the whole bot because one reaction landed on a
+     * deleted message, or one controller could not be resolved, is a worse failure than
+     * the one that caused it -- every other user is served by the same process.
+     *
+     * Nothing is silenced. The error is logged against the event that produced it, so a
+     * genuine misconfiguration -- an unbound controller, a missing dependency -- shows
+     * up on the very first interaction rather than staying hidden.
+     *
+     * @param event - The gateway event being handled, named in the log.
+     * @param run - The handler to run.
+     */
+    private runListener;
+    /**
+     * Rotates the bot's activity.
+     *
+     * Guarded separately from {@link runListener}: this runs on a timer rather than an
+     * event, and a throw from a timer callback is an uncaught exception no listener
+     * wrapper can reach.
+     */
+    private updateActivity;
+    private getInstance;
+    /**
+     * Registers the Discord event handlers and logs in.
+     *
+     * Rejects when the login fails -- an invalid token, or Discord unreachable -- so the caller can
+     * stop with a non-zero exit code. A bot that never came online is a failed start, and a
+     * supervisor such as Docker's `restart: on-failure` or systemd can only tell if the process says so.
+     */
+    start(): Promise<void>;
+    registerCommands(): Promise<void>;
+    /**
+     * Every pattern-matched route, ordered most specific first.
+     *
+     * Built once and cached, so dispatch stays a single ordered walk with an early exit
+     * rather than paying to rank anything per interaction. Ordering here is what lets
+     * `gi-profile/summary/{ownerId}/{uid}` keep the ids it owns when
+     * `gi-profile/{uuid}/{uid}` would also match them — without it, the winner would be
+     * whichever controller happened to be registered first.
+     */
+    private componentRoutes?;
+    private getComponentRoutes;
+    /**
+     * Warns rather than throws: an app whose patterns overlap boots and works today, and
+     * refusing to start would turn a latent mis-route into an outage on upgrade.
+     */
+    private reportAmbiguousRoutes;
+    /**
+     * Every `@Autocomplete` handler, ordered so an option-specific handler is found
+     * before a command-wide one.
+     *
+     * Cached alongside the component table: autocomplete fires on every keystroke, and
+     * rebuilding the list per keystroke would put reflection on the hottest path the
+     * framework has.
+     */
+    private autocompleteRoutes?;
+    private getAutocompleteRoutes;
+    /**
+     * Dispatches an interaction, and makes sure a failure anywhere in that still reaches
+     * the person who triggered it.
+     *
+     * {@link executeCommand} already reports what a handler throws, but everything
+     * *before* the handler can fail too — resolving a controller through the container
+     * is the common case — and a component that fails there would otherwise look dead
+     * with nothing said to the user and nothing in the log.
+     */
+    private handleInteraction;
+    private dispatchInteraction;
+    /**
+     * The names a command interaction can be handled under, most specific first.
+     *
+     * Empty for anything that is not a registered command, which is how a component
+     * whose customId matched no pattern falls through to the unmatched warning instead
+     * of being looked up under a name it does not have.
+     */
+    private resolveNameRoutes;
+    /**
+     * Answers an autocomplete interaction from the `@Autocomplete` handler that claims it.
+     *
+     * Discord closes the window after three seconds and shows a loading state until
+     * something arrives, so an unclaimed option is answered with an empty list rather
+     * than left to time out -- a visibly empty menu is a better failure than a stuck one,
+     * and the warning says which option is missing a handler.
+     */
+    private handleAutocomplete;
+    /** Closes an autocomplete window that nothing else answered. */
+    private respondEmpty;
+    /**
+     * Runs a resolved command, shared by both dispatch paths so a pattern-matched
+     * component and a named slash command behave identically once the route is chosen.
+     */
+    private executeCommand;
+    /**
+     * Tells the user something went wrong, if the interaction can still hear it.
+     *
+     * A handler that replies and *then* throws is the common shape of a failure, and
+     * replying twice throws in turn -- out of the catch block, where nothing is left to
+     * handle it. Whatever the interaction's state, reporting an error must not be able
+     * to become a second, worse one.
+     */
+    private replyWithError;
+    private handleMessage;
+    private handleReaction;
+    private gracefulShutdown;
+}
+
+declare class MeoCordFactory {
+    private static logger;
+    static create(target: ServiceIdentifier): MeoCordApp;
+}
+
+export { MeoCordFactory };

package/dist/types/core/index.d.ts

@@ -39,6 +39,13 @@ declare class MeoCordApp {
      */
     private updateActivity;
     private getInstance;
+    /**
+     * Registers the Discord event handlers and logs in.
+     *
+     * Rejects when the login fails -- an invalid token, or Discord unreachable -- so the caller can
+     * stop with a non-zero exit code. A bot that never came online is a failed start, and a
+     * supervisor such as Docker's `restart: on-failure` or systemd can only tell if the process says so.
+     */
     start(): Promise<void>;
     registerCommands(): Promise<void>;
     /**