meocord 4.2.2 → 4.2.3

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

@@ -1,12 +1,13 @@
 import { REST, Routes, Message } from 'discord.js';
 import { Logger, hideInLogs } from '../common/logger.js';
-import { warnDeprecatedBehaviour } from '../common/deprecation.js';
-import './theme-scope.js';
-import './theme-validation.js';
+import '../common/theme.js';
 import '../common/decorator.js';
 import 'reflect-metadata';
+import { warnDeprecatedBehaviour } from '../common/deprecation.js';
 import '../common/response/response-state.js';
+import './theme-scope.js';
 import { GuardDeniedError, UserError } from '../common/errors.js';
+import '../common/cooldown-store.js';
 import 'node:crypto';
 import { getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import './scalar-types.js';
@@ -15,18 +16,17 @@ import { managerGone } from '../util/sharding-mode.util.js';
 import '../common/translator.js';
 import '../common/meocord-text.js';
 import { markExplained } from '../common/explained-error.js';
+import './theme-resolvers.js';
 import { messageDecorator, reactionDecorator } from './command-conflicts.js';
 import { ReactionHandlerAction } from '../enum/controller.enum.js';
 import { globalStagesOf, runHandler } from './handler-pipeline.js';
 import { createFallback, replyWithUserError } from './fallback.js';
 import { waitForCooldownStore, claimStoreDownNotice, claimCooldownNotice } from './cooldown-runner.js';
 import { stageTypes, stageClass } from './stage-scope.js';
-import { getEventHandlers } from '../decorator/event.decorator.js';
 import { eventRequirements, messageHandlerRequirements, REACTION_HANDLER_REQUIREMENTS, missingRequirementWarnings } from './event-requirements.js';
-import { classUnits } from './lifecycle-order.js';
-import { runReadyHooks, runShutdownSequence, ReadyPass } from './lifecycle-hooks.js';
+import { runShutdownSequence, runReadyHooks, lifecycleEntry, ReadyPass } from './lifecycle-hooks.js';
 import { RunningCalls } from './running-calls.js';
-import { stopRequests } from '../util/stop-request.util.js';
+import { processState } from './process-state.js';
 import { tellDevRunner, onDevRunnerStop } from '../util/dev-runner.util.js';
 import { fatalLoginCode, explainLoginFailure, tokenMessage, isRefusedToken } from './login-failure.js';
 import { endFailedShard, tellManager } from './shard-exit.js';
@@ -36,21 +36,18 @@ import { undoFailedLogin } from './failed-login.js';
 import { ownInteractionListener, Dispatcher } from './dispatcher.js';
 import { deliverUncachedDmReactions } from './dm-reactions.js';
 import { loadMeoCordConfig } from '../util/meocord-config-loader.util.js';
-import { isRegisterOnly, FORCE_REGISTER_ENV, REGISTER_GUILD_ENV } from '../util/registration-mode.util.js';
+import { isRegisterOnly, FORCE_REGISTER_ENV, registersAsDevelopment, REGISTER_GUILD_ENV } from '../util/registration-mode.util.js';
 import { shutdownTimeoutOf } from '../util/shutdown-timeout.util.js';
 import { escapeForLog } from '../util/user-text.util.js';
 
 /** How long an `onReady` hook runs before a warning says the hooks after it are waiting. */ const SLOW_READY_HOOK_MS = 10000;
-/** Closes each started app: runs its shutdown hooks and destroys its client, resolving `false` on failure. */ const runningApps = new Set();
-const stopRequest = stopRequests();
-let signalHandlersInstalled = false;
-let shuttingDown;
+const { runningApps } = processState;
 /**
- * Shuts every started app down and exits, with a code already set or 0, and 1 if a client failed to close. Signals call
- * it, and in a shard its manager's request or its going. A call within `REPEAT_SIGNAL_WINDOW_MS` of the first is the
+ * Shuts every started app down and exits, with the code set when the shutdown began or 0, and 1 if an app failed to
+ * close. Signals call it, and in a shard its manager's request or its going. A call within `REPEAT_SIGNAL_WINDOW_MS` of the first is the
  * same request; one after it forces exit 1, except in a shard, whose manager forces it.
  */ async function shutdownAndExit(shard) {
-    const request = stopRequest();
+    const request = processState.stopRequest();
     if (request !== 'first') {
         // A shard hears Ctrl+C both directly and from its manager, which owns forcing it; so it waits
         if (request === 'duplicate' || shard) return;
@@ -60,23 +57,28 @@ let shuttingDown;
     return shutDown();
 }
 /** The one shutdown of the process, however many ask for it: a stop request joins one already under way. */ function shutDown() {
-    shuttingDown ?? (shuttingDown = (async ()=>{
+    var _processState;
+    (_processState = processState).shuttingDown ?? (_processState.shuttingDown = (async ()=>{
+        // A clean stop keeps a code already set, such as the 1 a failed login set, so a supervisor still sees it. Read as
+        // the shutdown begins: a code main.ts sets as it hears of the stop is the stop's, not a failure.
+        const exitCode = Number(process.exitCode ?? 0) || 0;
         const closed = await Promise.all([
             ...runningApps
         ].map((close)=>close()));
-        // A clean stop keeps a code already set, such as the 1 a failed login set, so a supervisor still sees it
-        process.exit(closed.every(Boolean) ? Number(process.exitCode ?? 0) || 0 : 1);
+        process.exit(closed.every(Boolean) ? exitCode : 1);
     })());
-    return shuttingDown;
+    return processState.shuttingDown;
 }
+/** The errors {@link stoppedBeforeOnline} made, which end a start without being its failure. */ const stops = new WeakSet();
 /** What `start()` rejects with when shutdown begins before the bot came online, which shutdown has logged. */ function stoppedBeforeOnline() {
     const error = new Error('The bot was stopped before it came online.');
     markExplained(error);
+    stops.add(error);
     return error;
 }
 /** One pair of signal listeners for the process, however many apps it starts, for the role the first decided. */ function installSignalHandlers(shard) {
-    if (signalHandlersInstalled) return;
-    signalHandlersInstalled = true;
+    if (processState.signalHandlersInstalled) return;
+    processState.signalHandlersInstalled = true;
     process.on('SIGINT', ()=>void shutdownAndExit(shard));
     process.on('SIGTERM', ()=>void shutdownAndExit(shard));
     // How `meocord start --dev` stops the application to restart it, a signal being no graceful stop on Windows. It is
@@ -129,13 +131,21 @@ class MeoCordApp {
         }
     }
     /**
-   * Logs the bot in, as {@link MeoCordApplication.start} describes. The providers, services and event handlers are set
-   * up once, or again after a provider's factory failed; a retry after a failed login reuses them.
+   * Logs the bot in, as {@link MeoCordApplication.start} describes. The event handlers are attached once; the providers
+   * and services are made for each start, as a failed one, of a factory or the login, shuts them down and drops them.
    */ async start() {
         if (isRegisterOnly()) return this.registerOnly();
         if (this.stopped) throw new Error('This app was stopped; use MeoCordFactory.create to make a new one.');
         if (this.online) return;
-        this.starting ?? (this.starting = this.startOnce().catch((error)=>{
+        this.starting ?? (this.starting = this.startOnce().catch(async (error)=>{
+            // A failed start stays among the running apps while it shuts down what it made, which a stop meanwhile waits
+            // for, and then while it holds a value it was given open, which a signal closes as stop() does. One that holds
+            // nothing leaves, so a signal later stops only the apps that run; a stopped start stays until its close settles
+            if (!this.closing) {
+                this.undoing = this.undoStart().finally(()=>this.undoing = undefined);
+                await this.undoing;
+                if (!this.closing && !this.holdsOpen()) runningApps.delete(this.close);
+            }
             // A shard ends, for its manager to restart, or to stop all if told it is fatal; a stopped start is the stop's
             if (this.shard && !this.closing) endFailedShard(error);
             throw error;
@@ -156,6 +166,30 @@ class MeoCordApp {
         // As a signal's shutdown exits 1 for a client that failed to close, a code another failure set aside
         if (!await this.close() && !process.exitCode) process.exitCode = 1;
     }
+    /**
+   * Shuts down what a failed start made, by the rule a stop follows, and drops it from the container, so the process
+   * holds nothing of it open and a retry makes it afresh.
+   */ async undoStart() {
+        if (!this.attempt || !this.begun) return;
+        this.begun = false;
+        const { given, constructed } = this.attempt;
+        const entries = this.shutdownEntries().filter(({ token })=>!given.has(token));
+        // A value the app gave stays constructed, so a stop with no retry still closes it
+        for (const token of constructed)if (!given.has(token)) constructed.delete(token);
+        this.readySettled.clear();
+        this.attempt.drop();
+        this.made = false;
+        // Nothing came online, so no call runs and no listener needs removing
+        await runShutdownSequence(this.container, ()=>entries, {
+            drainCalls: ()=>this.calls.settled(),
+            timeoutMs: this.shutdownTimeout,
+            hookFailed: (name, error)=>this.logger.error(`onShutdown failed in ${name}:`, error),
+            warn: (message)=>this.logger.warn(message)
+        });
+    }
+    /** Whether a shutdown has an `onShutdown` to run, as for a value the app gave once a failed start is undone. */ holdsOpen() {
+        return this.shutdownEntries().some(({ instance })=>typeof instance.onShutdown === 'function');
+    }
     async startOnce() {
         this.logger.log('Starting bot...');
         // Before the providers are made, so a signal, or a shard's manager, can stop a start that is slow to come online
@@ -166,7 +200,9 @@ class MeoCordApp {
         // A bot runs one app, whose theme code outside any call reads, its providers' factories included; claimed for
         // each start, as a failed one gives it up
         claimAmbientAppTheme(this.container);
-        if (!this.prepared) {
+        if (!this.made) {
+            this.attempt?.begin();
+            this.begun = true;
             // Kept while it runs, so a stop meanwhile waits for it
             this.preparing = this.prepare();
             try {
@@ -174,7 +210,11 @@ class MeoCordApp {
             } finally{
                 this.preparing = undefined;
             }
-            this.prepared = true;
+            this.made = true;
+        }
+        if (!this.attached) {
+            this.attachHandlers();
+            this.attached = true;
         }
         if (this.loginFailed) {
             warnDeprecatedBehaviour(this.logger, 'Retrying start() after a failed login', 'rejects', 'MeoCordFactory.create to make a new app');
@@ -182,7 +222,7 @@ class MeoCordApp {
         }
         await this.login();
     }
-    /** Makes the provided values and listed services, and attaches the Discord event handlers. */ async prepare() {
+    /** Makes the provided values and listed services. */ async prepare() {
         // Every provided value is made before anything that injects it is resolved, and before login
         if (this.startup) {
             try {
@@ -194,7 +234,7 @@ class MeoCordApp {
                 releaseAmbientAppTheme(this.container);
                 if (process.exitCode === undefined || process.exitCode === 0) {
                     process.exitCode = 1;
-                    MeoCordApp.failedLoginSetExitCode = true;
+                    processState.startFailureSetExitCode = true;
                 }
                 throw error;
             }
@@ -207,6 +247,8 @@ class MeoCordApp {
             this.storeReady = Promise.withResolvers();
             waitForCooldownStore(this.container, this.storeReady.promise);
         }
+    }
+    /** Attaches the Discord event handlers. */ attachHandlers() {
         this.bot.on('clientReady', (readyClient)=>this.runListener('clientReady', async ()=>{
                 // Only for activities the app listed: without them, a status it sets itself stays as it set it
                 if (this.activities?.length) {
@@ -231,9 +273,10 @@ class MeoCordApp {
                 })));
         // discord.js drops a reaction in a DM channel it has not cached; this fetches the channel and delivers it
         deliverUncachedDmReactions(this.bot, this.logger);
-        this.attachEventHandlers();
-        this.warnAboutMissingRequirements();
-        this.noteGlobalStagesOnEvents();
+        const sources = this.eventSources();
+        this.attachEventHandlers(sources);
+        this.warnAboutMissingRequirements(sources);
+        this.noteGlobalStagesOnEvents(sources);
     }
     /** Logs the bot in, setting the exit code when that fails and clearing it when a later attempt succeeds. */ async login() {
         // Checked here as well, after the last await before the login: from here to setting abortLogin runs in one turn,
@@ -254,7 +297,6 @@ class MeoCordApp {
             ]);
         } catch (error) {
             if (this.closing) throw error;
-            runningApps.delete(this.close);
             // A bot that never came online is not the app whose theme is read outside calls
             releaseAmbientAppTheme(this.container);
             const fatal = fatalLoginCode(error);
@@ -269,12 +311,12 @@ class MeoCordApp {
             if (fatal) await reportFatalLogin(this.shard, fatal, explanation ?? (error instanceof Error ? error.message : String(error)));
             if (process.exitCode === undefined || process.exitCode === 0) {
                 process.exitCode = 1;
-                MeoCordApp.failedLoginSetExitCode = true;
+                processState.startFailureSetExitCode = true;
             }
             await tellDevRunner({
                 meocord: 'login-failed'
             }, this.shard);
-            MeoCordApp.toldDevRunnerLoginFailed = true;
+            processState.toldDevRunnerLoginFailed = true;
             this.loginFailed = true;
             throw error;
         } finally{
@@ -283,12 +325,12 @@ class MeoCordApp {
         // A shutdown that began as the login completed has the client to close; the bot is not reported online
         if (this.closing) throw stoppedBeforeOnline();
         // 0 rather than undefined, which Bun ignores
-        if (MeoCordApp.failedLoginSetExitCode && process.exitCode === 1) {
+        if (processState.startFailureSetExitCode && process.exitCode === 1) {
             process.exitCode = 0;
-            MeoCordApp.failedLoginSetExitCode = false;
+            processState.startFailureSetExitCode = false;
         }
-        if (MeoCordApp.toldDevRunnerLoginFailed) {
-            MeoCordApp.toldDevRunnerLoginFailed = false;
+        if (processState.toldDevRunnerLoginFailed) {
+            processState.toldDevRunnerLoginFailed = false;
             await tellDevRunner({
                 meocord: 'online'
             }, this.shard);
@@ -298,11 +340,16 @@ class MeoCordApp {
     }
     /**
    * Registers the application's commands with Discord, where `meocord.config.ts`'s `commands` says. Runs once the bot
-   * is ready, except in a shard, whose manager registers. It never throws: a failure is logged and the bot stays
+   * is ready, except in a shard, whose manager registers. Called before the bot is online, it logs a warning and
+   * registers nothing, as the application comes from the login. It never throws: a failure is logged and the bot stays
    * online.
    */ async registerCommands() {
+        // discord.js sets the application when the gateway's READY arrives
         const applicationId = this.bot.application?.id;
-        if (!applicationId) return;
+        if (!applicationId) {
+            this.logger.warn('registerCommands() registers nothing before the bot is online, as Discord names the application at login. ' + 'The bot registers once it is online; to register without logging in, run `meocord register`.');
+            return;
+        }
         const config = loadMeoCordConfig()?.commands;
         if (config?.register === false) {
             this.logger.log('Command registration is off (commands.register: false); run `meocord register` to register.');
@@ -314,7 +361,7 @@ class MeoCordApp {
             controllerClasses: this.controllerClasses,
             logger: this.logger,
             config,
-            development: process.env.NODE_ENV === 'development',
+            development: registersAsDevelopment(),
             force: process.env[FORCE_REGISTER_ENV] === '1'
         });
     }
@@ -345,24 +392,25 @@ class MeoCordApp {
             controllerClasses: this.controllerClasses,
             logger: this.logger,
             config: loadMeoCordConfig()?.commands,
-            development: process.env.NODE_ENV === 'development',
+            development: registersAsDevelopment(),
             onlyGuild: process.env[REGISTER_GUILD_ENV],
             force: true
         });
         process.exit(registered ? 0 : 1);
     }
     /**
-   * Adds a client listener for every `@On` and `@Once` handler on the app's controllers and services, each event run on
-   * the class's one instance from the container. Each call is isolated: an error is logged against the event and the
-   * handler, and the next listener still runs.
-   */ attachEventHandlers() {
-        for (const lifecycleClass of this.lifecycleClasses){
-            for (const { event, method, once } of getEventHandlers(lifecycleClass.prototype)){
-                const logError = (error)=>this.logger.error(`Error handling event "${event}" in ${lifecycleClass.name}.${method}:`, error);
+   * Adds a client listener for every `@On` and `@Once` handler on each instance whose lifecycle hooks run, in lifecycle
+   * order, each event run on the instance the container holds. Each call is isolated: an error is logged against the
+   * event and the handler, and the next listener still runs.
+   */ attachEventHandlers(sources) {
+        for (const source of sources){
+            const { name } = source.cls;
+            for (const { event, method, once } of source.handlers){
+                const logError = (error)=>this.logger.error(`Error handling event "${event}" in ${name}.${method}:`, error);
                 // An error no filter handles is logged, with the handler. A guard denying an event only filters which
                 // events the handler takes, and a UserError is meant for the sender of the event's message, if it has one
                 const fallback = async (error, context)=>{
-                    const where = `event "${event}" in ${lifecycleClass.name}.${method}`;
+                    const where = `event "${event}" in ${name}.${method}`;
                     if (error instanceof GuardDeniedError) this.logger.debug(`Denied ${where}: ${escapeForLog(error.message)}`);
                     else if (error instanceof UserError) {
                         this.logger.debug(`Refused ${where}: ${escapeForLog(error.message)}`);
@@ -374,12 +422,12 @@ class MeoCordApp {
                     } else logError(error);
                     return undefined;
                 };
-                const label = `@${once ? 'Once' : 'On'}('${event}') in ${lifecycleClass.name}.${method}`;
+                const label = `@${once ? 'Once' : 'On'}('${event}') in ${name}.${method}`;
                 // A call, as a dispatched one is, which shutdown waits for
                 const listener = (...args)=>this.calls.run(label, async ()=>{
                         try {
-                            const instance = this.container.get(lifecycleClass);
-                            await runHandler(this.container, instance, method, args, {
+                            const instance = source.resolve();
+                            if (instance) await runHandler(this.container, instance, method, args, {
                                 fallback,
                                 type: 'event'
                             });
@@ -396,8 +444,8 @@ class MeoCordApp {
     /**
    * Says, once per stage, which global guards and interceptors declare no `types` and so also run
    * before `@On` and `@Once` handlers, when the app has any.
-   */ noteGlobalStagesOnEvents() {
-        if (!this.lifecycleClasses.some((cls)=>getEventHandlers(cls.prototype).length > 0)) return;
+   */ noteGlobalStagesOnEvents(sources) {
+        if (sources.length === 0) return;
         const { guards, interceptors } = globalStagesOf(this.container);
         for (const [label, decorator, entries] of [
             [
@@ -420,29 +468,29 @@ class MeoCordApp {
     /**
    * Warns about handlers whose events the client options will not deliver, once per missing intent or partial. Only a
    * controller's message and reaction handlers are counted, as only those run.
-   */ warnAboutMissingRequirements() {
+   */ warnAboutMissingRequirements(sources) {
         const options = this.bot.options;
         if (!options?.intents) return;
-        const controllers = new Set(this.controllerClasses);
         const handlers = [];
-        for (const lifecycleClass of this.lifecycleClasses){
-            const prototype = lifecycleClass.prototype;
-            for (const { event, method, once } of getEventHandlers(prototype)){
+        for (const { cls, handlers: events } of sources){
+            for (const { event, method, once } of events){
                 handlers.push({
-                    label: `@${once ? 'Once' : 'On'}('${event}') in ${lifecycleClass.name}.${method}`,
+                    label: `@${once ? 'Once' : 'On'}('${event}') in ${cls.name}.${method}`,
                     requirements: eventRequirements(event)
                 });
             }
-            if (!controllers.has(lifecycleClass)) continue;
+        }
+        for (const controller of this.controllerClasses){
+            const prototype = controller.prototype;
             for (const handler of getMessageHandlers(prototype)){
                 handlers.push({
-                    label: `${messageDecorator(handler.pattern)} in ${lifecycleClass.name}.${handler.method}`,
+                    label: `${messageDecorator(handler.pattern)} in ${controller.name}.${handler.method}`,
                     requirements: messageHandlerRequirements(handler, this.messageOptions ?? {})
                 });
             }
             for (const { emoji, method } of getReactionHandlers(prototype)){
                 handlers.push({
-                    label: `${reactionDecorator(emoji)} in ${lifecycleClass.name}.${method}`,
+                    label: `${reactionDecorator(emoji)} in ${controller.name}.${method}`,
                     requirements: REACTION_HANDLER_REQUIREMENTS
                 });
             }
@@ -454,11 +502,9 @@ class MeoCordApp {
    * at a time, in dependency order. A failure is logged and the next one still runs, with a warning for each hook
    * whose dependencies failed. Once shutdown begins, no further hook starts.
    */ async runReadyHooks(client) {
-        const entries = [];
-        this.lifecycleEntries = entries;
         await this.readyPass.run(()=>runReadyHooks(this.container, this.lifecycleUnits, client, {
                 primary: client.shard ? client.shard.ids.includes(0) : true
-            }, entries, {
+            }, {
                 resolveFailed: (unit, error)=>this.logger.error(`Could not resolve ${unit.name} to run its lifecycle hooks:`, error),
                 hookFailed: (unit, error)=>this.logger.error(`onReady failed in ${unit.name}:`, error),
                 dependsOnFailed: (unit, failed)=>this.logger.warn(`Running onReady in ${unit.name} although it depends on ${failed.map(({ name })=>name).join(', ')}, which failed.`),
@@ -467,15 +513,37 @@ class MeoCordApp {
             {
                 stopped: ()=>this.closing,
                 slowAfterMs: SLOW_READY_HOOK_MS,
-                settled: (unit)=>unit.cooldownStore && this.storeReady?.resolve(),
+                settled: (unit)=>{
+                    this.readySettled.add(unit.token);
+                    if (unit.cooldownStore) this.storeReady?.resolve();
+                },
                 runOnReady: this.readyPass.runOnReady
             }));
         // Also when shutdown stopped the hooks before the store's, so no call waits on it
         this.storeReady?.resolve();
     }
-    /** Runs the `onShutdown` hooks through the shutdown sequence, within the configured `shutdownTimeout`. */ async runShutdownHooks() {
-        // Read once the onReady in progress settled; a login that failed never ran onReady, so there is no onShutdown to undo
-        await runShutdownSequence(this.container, ()=>this.lifecycleEntries ?? [], {
+    /**
+   * The units a shutdown closes: each one the container constructed whose `onReady`, and that of every unit it depends
+   * on, has settled or doesn't exist, in dependency order. A unit whose `onReady` never ran gets no `onShutdown`, so a
+   * hook that undoes `onReady` never runs without it, and neither does anything that depends on it.
+   */ shutdownEntries() {
+        const units = new Set(this.lifecycleUnits.map(({ token })=>token));
+        const closes = new Set();
+        const entries = [];
+        for (const unit of this.lifecycleUnits){
+            if (!this.attempt?.constructed.has(unit.token)) continue;
+            // Already made, so this returns the instance; a provided value may be anything, null included
+            const instance = this.container.get(unit.token) ?? {};
+            const ready = typeof instance.onReady !== 'function' || this.readySettled.has(unit.token);
+            if (!ready || unit.dependencies.some((dependency)=>units.has(dependency) && !closes.has(dependency))) continue;
+            closes.add(unit.token);
+            entries.push(lifecycleEntry(unit, instance));
+        }
+        return entries;
+    }
+    /** Runs the `onShutdown` hooks through the shutdown sequence, within `timeoutMs`: the stop's share of `shutdownTimeout`. */ async runShutdownHooks(timeoutMs) {
+        // Read once the onReady in progress settled
+        await runShutdownSequence(this.container, ()=>this.shutdownEntries(), {
             // No new call starts once the listeners are gone; an error the client emits meanwhile still has its listeners
             drainCalls: ()=>{
                 const emitter = this.bot;
@@ -485,7 +553,7 @@ class MeoCordApp {
             drainAlways: true,
             runningCalls: ()=>this.calls.running(),
             readyPass: this.readyPass,
-            timeoutMs: this.shutdownTimeout,
+            timeoutMs,
             hookFailed: (name, error)=>this.logger.error(`onShutdown failed in ${name}:`, error),
             warn: (message)=>this.logger.warn(message)
         });
@@ -493,7 +561,8 @@ class MeoCordApp {
     /**
    * Runs the shutdown hooks, if the ready hooks ran, then destroys the client; a stop during login ends the login.
    *
-   * @returns Whether the client closed cleanly, which an ended login counts as.
+   * @returns Whether the client closed cleanly, which an ended login counts as, and the startup it waited for, if any,
+   * did not fail.
    */ async closeClient() {
         this.closing = true;
         try {
@@ -506,56 +575,71 @@ class MeoCordApp {
     /**
    * Waits for the startup under way to stop making providers and services, at most `shutdownTimeout`; past it, warns
    * with the factory it still awaits, which then makes nothing more.
+   *
+   * @returns Whether the startup failed meanwhile, as a provider's factory that rejects does, rather than stopping.
    */ async waitForStartup(preparing) {
         let timer;
         const outlasted = new Promise((resolve)=>{
-            timer = setTimeout(()=>resolve(true), this.shutdownTimeout);
+            timer = setTimeout(()=>resolve('outlasted'), this.shutdownTimeout);
         });
-        const settled = preparing.then(()=>false, ()=>false);
-        if (await Promise.race([
+        const settled = preparing.then(()=>'stopped', (error)=>error instanceof Error && stops.has(error) ? 'stopped' : 'failed');
+        const outcome = await Promise.race([
             settled,
             outlasted
-        ])) {
+        ]);
+        clearTimeout(timer);
+        if (outcome === 'outlasted') {
             const what = this.pendingProvider ? `the factory providing ${this.pendingProvider}` : 'its providers';
             this.logger.warn(`The startup still waits for ${what} after ${this.shutdownTimeout} ms; shutting down without it.`);
         }
-        clearTimeout(timer);
+        return outcome === 'failed';
     }
     async shutDownClient() {
         this.logger.log('Shutting down bot...');
-        // So nothing is made after the bot has shut down
-        if (this.preparing) await this.waitForStartup(this.preparing);
-        // Nothing came online, so there are no hooks to undo; the listeners go first, so none of them runs
+        // A failed start's shutdown under way finishes first, so its hooks run in full, before those of what it left open.
+        // `shutdownTimeout` bounds the whole stop, as a shard's manager waits only that long, so the rest gets what is left
+        let timeoutMs = this.shutdownTimeout;
+        if (this.undoing) {
+            const waitedFrom = Date.now();
+            await this.undoing;
+            timeoutMs = Math.max(0, timeoutMs - (Date.now() - waitedFrom));
+        }
+        // So nothing is made after the bot has shut down; a factory that fails meanwhile is a failure of the stop too
+        const startupFailed = this.preparing !== undefined && await this.waitForStartup(this.preparing);
+        // Nothing came online, so no onReady ran; the listeners go first, so none of them runs, then what the start made
+        // without an onReady to wait for shuts down
         if (this.abortLogin) {
             this.logger.log('The bot was still logging in, so it stops without coming online');
             this.bot.removeAllListeners();
             this.abortLogin();
+            await this.runShutdownHooks(timeoutMs);
             this.logger.log('Bot has shut down');
             return true;
         }
         if (this.activityInterval) clearInterval(this.activityInterval);
         // The calls drain on every shutdown, and the onReady in progress settles first
-        await this.runShutdownHooks();
+        await this.runShutdownHooks(timeoutMs);
         try {
             this.bot.removeAllListeners();
             await this.bot.destroy();
             this.logger.log('Bot has shut down');
-            return true;
+            return !startupFailed;
         } catch (error) {
             this.logger.error('Error during shutdown:', error);
             return false;
         }
     }
-    constructor(controllerClasses, container, discordClient, discordToken, activities, lifecycleClasses = [], shutdownTimeout, startup, lifecycleUnits, messageOptions = {}, warnUnanswered = false, /** Whether a manager spawned this process, as `MeoCordFactory.create` decided before anything could change it. */ shard = false){
+    constructor(controllerClasses, container, discordClient, discordToken, activities, /** The instances whose `@On` and `@Once` handlers run, read once the providers are made. */ eventSources = ()=>[], shutdownTimeout, startup, lifecycleUnits, messageOptions = {}, warnUnanswered = false, /** Whether a manager spawned this process, as `MeoCordFactory.create` decided before anything could change it. */ shard = false, /** What each start makes; without one, as an app built by hand in a spec, nothing is shut down before ready. */ attempt){
         this.controllerClasses = controllerClasses;
         this.container = container;
         this.discordClient = discordClient;
         this.discordToken = discordToken;
         this.activities = activities;
-        this.lifecycleClasses = lifecycleClasses;
+        this.eventSources = eventSources;
         this.startup = startup;
         this.messageOptions = messageOptions;
         this.shard = shard;
+        this.attempt = attempt;
         this.logger = new Logger(MeoCordApp.name);
         this.fallback = createFallback(this.logger, ()=>this.messageOptions, {
             cooldownNotice: (refusal)=>claimCooldownNotice(this.container, refusal),
@@ -564,18 +648,21 @@ class MeoCordApp {
         this.activityInterval = null;
         /** Where the activities' rotation is: the index of the next one shown. */ this.nextActivity = 0;
         /** Whether shutdown has begun, so the ready hooks start no more. */ this.closing = false;
+        /** The tokens of the units whose `onReady` the ready pass has settled, or found they have none. */ this.readySettled = new Set();
         /**
    * Closes the app once, however many stops and signals ask: whether the client was destroyed cleanly. The app stays
    * among the running ones until the close settles, so a signal or a manager's request meanwhile waits for it.
    */ this.close = ()=>this.stopped ?? (this.stopped = this.closeClient().finally(()=>runningApps.delete(this.close)));
         /** The calls under way, which shutdown waits for, less one that asked the app to stop. */ this.calls = new RunningCalls();
         /** The ready hooks' pass, whose `onReady` in progress shutdown waits for, less one that asked the app to stop. */ this.readyPass = new ReadyPass();
-        /** Whether the providers, services and event handlers are set up, which a retry after a failed login reuses. */ this.prepared = false;
+        /** Whether a start has marked where it began and not been undone, so a failed one drops what it made exactly once. */ this.begun = false;
+        /** Whether this start's providers and services are made; a failed start drops them, so a retry makes them again. */ this.made = false;
+        /** Whether the Discord event handlers are attached, once for the app: they resolve what they run as each event comes. */ this.attached = false;
         /** Whether the bot logged in, after which `start()` has nothing to do. */ this.online = false;
         /** Whether a login of this app failed, so a retry restores the client discord.js destroyed. */ this.loginFailed = false;
         // First, so nothing logged from here on, before login or after, prints it
         hideInLogs(discordToken);
-        this.lifecycleUnits = lifecycleUnits ?? classUnits(container, lifecycleClasses);
+        this.lifecycleUnits = lifecycleUnits ?? [];
         this.bot = this.discordClient;
         // Built now, so a pattern that cannot be read or two that match the same messages or customIds stop the bot as it
         // is created, before start() attaches anything
@@ -593,7 +680,5 @@ class MeoCordApp {
         this.shutdownTimeout = shutdownTimeoutOf(shutdownTimeout, (message)=>this.logger.warn(message));
     }
 }
-/** Whether a failed login set the process exit code, so a later successful one knows to clear it. */ MeoCordApp.failedLoginSetExitCode = false;
-/** Whether `meocord start --dev` was told the bot could not log in, so a later login tells it the bot is online. */ MeoCordApp.toldDevRunnerLoginFailed = false;
 
 export { MeoCordApp, SLOW_READY_HOOK_MS, shutdownAndExit };

package/dist/esm/core/message-help.js

@@ -1,5 +1,5 @@
 import { fitsScope, commandWordsOf, afterStart } from './message-routes.js';
-import { isGuildType, primaryFirst, usageOf, paramTypeLabel } from './message-params.js';
+import { effectiveScope, primaryFirst, usageOf, paramTypeLabel } from './message-params.js';
 import { splitWords } from './message-words.js';
 import { usageHeading } from '../common/errors.js';
 import { textRenderer } from '../common/meocord-text.js';
@@ -31,12 +31,13 @@ import { userWords } from '../util/user-text.util.js';
     const text = content.trim();
     const rest = afterStart(text, starts.prefixes.filter((prefix)=>prefix !== ''), starts.mention, caseSensitive);
     if (!rest) return undefined;
-    const [first] = splitWords(rest);
+    const [first, second] = splitWords(rest);
     const key = (word)=>caseSensitive ? word : word.toLowerCase();
     if (!first || !words.some((word)=>key(word) === key(first.value))) return undefined;
+    // From where the next word starts, as the help word may have been written in quotes
     return {
         start: text.slice(0, text.length - rest.length),
-        query: rest.slice(first.value.length).trim()
+        query: second ? rest.slice(second.start).trim() : ''
     };
 }
 /** The start a caller would type a route with here: its own prefix, a mention, or the start the help message used. */ function displayStart(route, start, starts) {
@@ -45,11 +46,6 @@ import { userWords } from '../util/user-text.util.js';
     if (route.prefix !== undefined) return route.prefix[0] ?? '';
     return start;
 }
-/** Where a route works: its scope, narrowed to servers by a `member`, `role` or `channel` param or flag. */ function effectiveScope(route) {
-    if (route.scope !== 'any') return route.scope;
-    const guildOnly = route.tokens.some((token)=>'param' in token && token.type !== undefined && isGuildType(token.type)) || route.flags.some((flag)=>flag.type !== undefined && isGuildType(flag.type));
-    return guildOnly ? 'guild' : 'any';
-}
 /** A route's params and flags, each with what it takes in words. */ function paramsOf(route, types, render) {
     const params = route.tokens.flatMap((token)=>{
         if (!('param' in token)) return [];
@@ -294,4 +290,4 @@ let graphemes;
     return chunks;
 }
 
-export { computeMessageHelp, effectiveScope, helpInvocation, helpWords, isListable, matchHelpRequest, renderMessageHelp, splitReply };
+export { computeMessageHelp, helpInvocation, helpWords, isListable, matchHelpRequest, renderMessageHelp, splitReply };