meocord 4.0.0-beta.1 → 4.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # meocord
 
+## 4.0.0-beta.3
+
+### Patch Changes
+
+- [#40](https://github.com/l7aromeo/meocord/pull/40) [`3629edd`](https://github.com/l7aromeo/meocord/commit/3629eddaf20bd0947d24e5582aa167b2c0ca0d47) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Lint `meocord.config.ts`. The shared ESLint config from `meocord/eslint` ignored it, so the config
+  alone skipped the rules every other file follows — unused imports, formatting. It is linted like the
+  rest now; the typecheck it already gets is unchanged.
+
+- [#40](https://github.com/l7aromeo/meocord/pull/40) [`80b8302`](https://github.com/l7aromeo/meocord/commit/80b83021894ef8a964a12ac1610c2ec9b40f344e) Thanks [@l7aromeo](https://github.com/l7aromeo)! - Exit with code 1 when the login fails, whatever the entry point does. `app.start()` now sets
+  `process.exitCode = 1` before rejecting, so an existing `main.ts` whose `catch` only logs the error no
+  longer exits 0 — no `process.exitCode = 1` needs adding to it, and new applications' `main.ts` no
+  longer carries one.
+
+## 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,45 @@ class MeoCordApp {
         }
         return this.controllerInstancesCache.get(controllerClass);
     }
-    async start() {
+    /**
+   * Registers the Discord event handlers and logs in.
+   *
+   * Rejects when the login fails -- an invalid token, or Discord unreachable -- and sets the exit
+   * code to 1 first. 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. The exit code is
+   * set here rather than left to the entry point because an entry point that catches the rejection
+   * to log it has handled it, and the process would otherwise end with 0. A later `start()` that
+   * logs in -- an entry point retrying -- clears the code again, if this is what set it.
+   */ 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
+                })));
         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);
+            if (process.exitCode === undefined || process.exitCode === 0) {
+                process.exitCode = 1;
+                MeoCordApp.failedLoginSetExitCode = true;
+            }
+            throw error;
+        }
+        if (MeoCordApp.failedLoginSetExitCode && process.exitCode === 1) {
+            process.exitCode = undefined;
+            MeoCordApp.failedLoginSetExitCode = false;
         }
+        this.logger.log('Bot is online!');
     }
     async registerCommands() {
         // Keyed by type and name together, because that pair is what Discord treats as one
@@ -506,6 +523,7 @@ class MeoCordApp {
         process.on('SIGTERM', ()=>this.gracefulShutdown());
     }
 }
+/** Whether a failed login set the process exit code, so a later successful one knows to clear it. */ MeoCordApp.failedLoginSetExitCode = false;
 
 /**
  * File written beside a bundle that carries native addons, naming the platform it was built for.

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,45 @@ class MeoCordApp {
         }
         return this.controllerInstancesCache.get(controllerClass);
     }
-    async start() {
+    /**
+   * Registers the Discord event handlers and logs in.
+   *
+   * Rejects when the login fails -- an invalid token, or Discord unreachable -- and sets the exit
+   * code to 1 first. 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. The exit code is
+   * set here rather than left to the entry point because an entry point that catches the rejection
+   * to log it has handled it, and the process would otherwise end with 0. A later `start()` that
+   * logs in -- an entry point retrying -- clears the code again, if this is what set it.
+   */ 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
+                })));
         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);
+            if (process.exitCode === undefined || process.exitCode === 0) {
+                process.exitCode = 1;
+                MeoCordApp.failedLoginSetExitCode = true;
+            }
+            throw error;
+        }
+        if (MeoCordApp.failedLoginSetExitCode && process.exitCode === 1) {
+            process.exitCode = undefined;
+            MeoCordApp.failedLoginSetExitCode = false;
         }
+        this.logger.log('Bot is online!');
     }
     async registerCommands() {
         // Keyed by type and name together, because that pair is what Discord treats as one
@@ -488,5 +505,6 @@ class MeoCordApp {
         process.on('SIGTERM', ()=>this.gracefulShutdown());
     }
 }
+/** Whether a failed login set the process exit code, so a later successful one knows to clear it. */ MeoCordApp.failedLoginSetExitCode = false;
 
 export { MeoCordApp };

package/dist/esm/package.json.js

@@ -1,4 +1,4 @@
-var version = "4.0.0-beta.1";
+var version = "4.0.0-beta.3";
 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,136 @@
+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;
+    /** Whether a failed login set the process exit code, so a later successful one knows to clear it. */
+    private static failedLoginSetExitCode;
+    /**
+     * Registers the Discord event handlers and logs in.
+     *
+     * Rejects when the login fails -- an invalid token, or Discord unreachable -- and sets the exit
+     * code to 1 first. 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. The exit code is
+     * set here rather than left to the entry point because an entry point that catches the rejection
+     * to log it has handled it, and the process would otherwise end with 0. A later `start()` that
+     * logs in -- an entry point retrying -- clears the code again, if this is what set it.
+     */
+    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,18 @@ declare class MeoCordApp {
      */
     private updateActivity;
     private getInstance;
+    /** Whether a failed login set the process exit code, so a later successful one knows to clear it. */
+    private static failedLoginSetExitCode;
+    /**
+     * Registers the Discord event handlers and logs in.
+     *
+     * Rejects when the login fails -- an invalid token, or Discord unreachable -- and sets the exit
+     * code to 1 first. 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. The exit code is
+     * set here rather than left to the entry point because an entry point that catches the rejection
+     * to log it has handled it, and the process would otherwise end with 0. A later `start()` that
+     * logs in -- an entry point retrying -- clears the code again, if this is what set it.
+     */
     start(): Promise<void>;
     registerCommands(): Promise<void>;
     /**