@seedcord/core 0.9.0 → 0.9.2

package/README.md

@@ -6,7 +6,7 @@
 </div>
 
 <div align="center">
-  <h3>The whole Discord bot, wired and typed</h3>
+  <h3>The whole Discord bot, typed end to end</h3>
   <a href="https://seedcord.org">Website</a> ·
   <a href="https://guide.seedcord.org">Guide</a> ·
   <a href="https://docs.seedcord.org">Reference</a> ·

package/dist/{Pluggable-BShEwGw9.mjs → Pluggable-D-xWcaIv.mjs}

@@ -1,6 +1,6 @@
 import { n as asError, t as PublishDefault } from "./publishDefault-BuSZPbjT.mjs";
 import { n as StartupPhase } from "./phases-BauKJOTT.mjs";
-import { n as pluginLoggerOf, r as resolvedLifecycleSpecOf } from "./Plugin-BJfRk0s_.mjs";
+import { i as resolvedLifecycleSpecOf, n as extendsThisCorePlugin, r as pluginLoggerOf } from "./Plugin-CmNW5n6a.mjs";
 import { SeedcordErrorCode, isSeedcordError } from "@seedcord/errors";
 import { SeedcordAggregateError, SeedcordError, SeedcordTypeError } from "@seedcord/errors/internal";
 import { FRAMEWORK_CHANNELS, Logger } from "@seedcord/logger";
@@ -171,27 +171,6 @@ var Pluggable = class Pluggable {
 		Pluggable.isInstantiated = false;
 		return true;
 	}
-	/**
-	* Attaches a plugin under `key`. Read the instance back as `core[key]`. `seedcord codegen`
-	* writes the `Core` augmentation that types it there.
-	*
-	* Put one dot in the key to nest the plugin under a group, so `'services.users'` reads back as
-	* `core.services.users`. Each name holds one plugin or one group.
-	*
-	* Startup runs each plugin's `init()` in attach order within its phase.
-	*
-	* Attaching a plugin whose `transport` or `runtime` differs from this host fails to compile.
-	* Your constructor takes `CoreBase` as its first parameter (you don't need to pass it though).
-	* A narrower one fails to compile here.
-	*
-	* @param key - Also the channel the plugin logs on, dots included. Reserved channel names throw.
-	* @param args - Whatever your constructor takes after the host.
-	* @throws A **SeedcordError** if you attach after the bot has started. A taken or reserved key throws too.
-	* @example
-	* ```ts
-	* seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });
-	* ```
-	*/
 	attach(key, Plugin, ...args) {
 		if (this.isInitialized) throw new SeedcordError(SeedcordErrorCode.CorePluginAfterInit);
 		const dot = key.indexOf(".");
@@ -201,6 +180,7 @@ var Pluggable = class Pluggable {
 		if (head === "" || leaf === "") throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, "has an empty part."]);
 		if (leaf?.includes(".")) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, "has more than one dot."]);
 		this.assertFree(head, leaf, key);
+		if (!extendsThisCorePlugin(Plugin)) throw new SeedcordTypeError(SeedcordErrorCode.CorePluginFromOtherCore, [Plugin.name]);
 		const instance = new Plugin(this, ...args);
 		pluginLoggerOf(instance).setChannel(key);
 		this.plugins.push(instance);
@@ -333,4 +313,4 @@ function shutdownOf(host) {
 
 //#endregion
 export { withTimeout as a, settleWithin as i, shutdownOf as n, assertNodeVersion as r, Pluggable as t };
-//# sourceMappingURL=Pluggable-BShEwGw9.mjs.map
+//# sourceMappingURL=Pluggable-D-xWcaIv.mjs.map

package/dist/Pluggable-D-xWcaIv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Pluggable-D-xWcaIv.mjs","names":[],"sources":["../src/node/Lifecycle/withTimeout.ts","../src/node/assertNodeVersion.ts","../src/node/processErrors.ts","../src/node/Pluggable.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\n// calling start() in here turns its synchronous throw into a rejection\nasync function raceTimer(\n    start: () => Promise<unknown>,\n    timeoutMs: number,\n    onTimeout: (resolve: () => void, reject: (error: unknown) => void) => void\n): Promise<void> {\n    let timer: NodeJS.Timeout | undefined;\n    try {\n        await Promise.race([\n            start(),\n            new Promise<void>((resolve, reject) => {\n                // node's timer can go off before performance.now() reaches timeoutMs\n                const expiresAt = performance.now() + timeoutMs;\n                const tick = (): void => {\n                    const remaining = expiresAt - performance.now();\n                    if (remaining > 0) {\n                        timer = setTimeout(tick, remaining);\n                        return;\n                    }\n                    onTimeout(resolve, reject);\n                };\n                timer = setTimeout(tick, timeoutMs);\n            })\n        ]);\n    } finally {\n        if (timer) clearTimeout(timer);\n    }\n}\n\n// rejects with a LifecycleTaskTimeout when run outlasts the bound\nexport function withTimeout(name: string, run: () => Promise<void>, timeoutMs: number): Promise<void> {\n    return raceTimer(run, timeoutMs, (_, reject) => {\n        reject(new SeedcordError(SeedcordErrorCode.LifecycleTaskTimeout, [name, timeoutMs]));\n    });\n}\n\n// the caller does not get work's rejection\nexport function settleWithin(work: Promise<unknown>, timeoutMs: number): Promise<void> {\n    return raceTimer(\n        () =>\n            work.then(\n                () => undefined,\n                () => undefined\n            ),\n        timeoutMs,\n        (resolve) => resolve()\n    );\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\n// every seedcord package declares engines.node as `>=major` or `>=major.minor`\nconst RANGE = new RegExp(String.raw`^>=(\\d+)(?:\\.(\\d+))?`);\nconst VERSION = /^v?(\\d+)\\.(\\d+)/;\nconst SPACES = /\\s/g;\n\n/** @internal */\nexport function assertNodeVersion(range: string, running: string): void {\n    const required = RANGE.exec(range.replaceAll(SPACES, ''));\n    const current = VERSION.exec(running);\n    if (!required || !current) return;\n\n    const [, requiredMajor, requiredMinor = '0'] = required;\n    const [, currentMajor, currentMinor] = current;\n\n    const meetsRange =\n        Number(currentMajor) > Number(requiredMajor) ||\n        (Number(currentMajor) === Number(requiredMajor) && Number(currentMinor) >= Number(requiredMinor));\n    if (meetsRange) return;\n\n    throw new SeedcordError(SeedcordErrorCode.UnsupportedNodeVersion, [range, running]);\n}\n","import crypto from 'node:crypto';\n\nimport { Logger } from '@seedcord/logger';\n\nimport { asError } from '#stops/asError';\nimport { PublishDefault } from '#subscribers/publishDefault';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { CoordinatedShutdown } from '#node/Lifecycle/CoordinatedShutdown';\n\nconst logger = new Logger('Faults', { channel: 'errors' });\n\n/** @internal */\nexport function registerProcessErrors(core: CoreBase, shutdown: CoordinatedShutdown): () => void {\n    function report(caught: unknown, origin: string): void {\n        const error = asError(caught);\n        const uuid = crypto.randomUUID();\n\n        if (core.config.errors?.errorStack ?? false) logger.error(uuid, error);\n        else logger.error(`${uuid} | ${error.message}`);\n\n        core.bus[PublishDefault]('unknownException', { uuid, dispatchId: null, error, origin });\n    }\n\n    const onRejection = (reason: unknown): void => {\n        report(reason, 'process:unhandledRejection');\n    };\n\n    const onException = (caught: unknown): void => {\n        report(caught, 'process:uncaughtException');\n        // node does not exit on its own once a listener is registered\n        void shutdown.run(1);\n    };\n\n    process.on('unhandledRejection', onRejection);\n    process.on('uncaughtException', onException);\n\n    return () => {\n        process.off('unhandledRejection', onRejection);\n        process.off('uncaughtException', onException);\n    };\n}\n","import { SeedcordErrorCode, isSeedcordError } from '@seedcord/errors';\nimport { SeedcordAggregateError, SeedcordError, SeedcordTypeError } from '@seedcord/errors/internal';\nimport { FRAMEWORK_CHANNELS, Logger } from '@seedcord/logger';\nimport { HostPluginKeys, HostShutdown, HostStartup } from '@seedcord/types/internal';\n\nimport { assertNodeVersion } from '#node/assertNodeVersion';\nimport { StartupPhase } from '#src/lifecycle/phases';\nimport { extendsThisCorePlugin, pluginLoggerOf, resolvedLifecycleSpecOf } from '#src/plugin/Plugin';\n\nimport { withTimeout } from './Lifecycle/withTimeout';\nimport { registerProcessErrors } from './processErrors';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { CoordinatedShutdown } from '#node/Lifecycle/CoordinatedShutdown';\nimport type { CoordinatedStartup } from '#node/Lifecycle/CoordinatedStartup';\nimport type { ShutdownPhase } from '#src/lifecycle/phases';\nimport type { Runtime, Transport } from '#src/plugin/options';\nimport type { AttachableCtor, Attached, AttachKeyAssert, PluginArgs, PluginCtor, PluginLike } from '#src/plugin/Plugin';\nimport type { Bus } from '#subscribers/Bus';\nimport type { REST } from '@discordjs/rest';\nimport type { Config, IRateLimiter } from '@seedcord/types';\n\ninterface Attachment {\n    readonly key: string;\n    readonly instance: PluginLike;\n}\n\nconst RESERVED_KEYS: ReadonlySet<string> = new Set(FRAMEWORK_CHANNELS);\n\n/**\n * Base class for a plugin host, a transport `Seedcord` class.\n *\n * You attach plugins while configuring the bot. Within one startup phase, their `init()` calls run\n * one after another in attach order.\n */\n// BotRt has no default because RuntimeAssert rejects every plugin once 'edge' is in the union\nexport abstract class Pluggable<BotT extends Transport, BotRt extends Runtime> implements CoreBase {\n    public abstract readonly config: Config;\n    public abstract readonly rest: REST;\n    public abstract readonly applicationId: string;\n    public abstract readonly rateLimiter: IRateLimiter;\n    public abstract readonly bus: Bus;\n\n    /** @internal */\n    readonly [HostShutdown]: CoordinatedShutdown;\n    /** @internal */\n    readonly [HostStartup]: CoordinatedStartup;\n\n    /** Add a task that runs while the bot shuts down. */\n    public readonly shutdown: Pick<CoordinatedShutdown, 'addTask'>;\n\n    /** Add a task that runs while the bot starts. */\n    public readonly startup: Pick<CoordinatedStartup, 'addTask'>;\n\n    protected isInitialized = false;\n    protected startFailed = false;\n    protected readonly plugins: PluginLike[] = [];\n    private readonly groups = new Map<string, Record<string, PluginLike>>();\n\n    private readonly pluginLogger = new Logger('Plugins', { channel: 'plugins' });\n\n    private readonly attachments: Attachment[] = [];\n    private readonly completedInits = new Set<Attachment>();\n    private readonly disposePhases = new Set<ShutdownPhase>();\n    private pluginTasksRegistered = false;\n    private initPromise?: Promise<this> | undefined;\n\n    private static isInstantiated = false;\n    private static liveHost?: object | undefined;\n    private static liveShutdown?: CoordinatedShutdown | undefined;\n    private static liveProcessErrors?: (() => void) | undefined;\n\n    constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup) {\n        // a `sideEffects: false` build would drop the same call in the node entry\n        assertNodeVersion(process.env.PACKAGE_NODE_RANGE ?? '', process.version);\n\n        if (Pluggable.isInstantiated) {\n            // signal handlers from the caller's shutdown stay on the process unless dropped here\n            shutdown.removeSignalHandlers();\n            throw new SeedcordError(SeedcordErrorCode.CoreSingletonViolation);\n        }\n\n        Pluggable.isInstantiated = true;\n        Pluggable.liveHost = this;\n        Pluggable.liveShutdown = shutdown;\n        this[HostShutdown] = shutdown;\n        this[HostStartup] = startup;\n        // a getter returning the slot would expose run() and the signal handlers too\n        this.shutdown = { addTask: shutdown.addTask.bind(shutdown) };\n        this.startup = { addTask: startup.addTask.bind(startup) };\n    }\n\n    /** @internal */\n    protected init(): Promise<this> {\n        // clearing the slot on a rejection means a later retry throws its own error\n        this.initPromise ??= this.runInit().catch((caught: unknown) => {\n            this.initPromise = undefined;\n            throw caught;\n        });\n        return this.initPromise;\n    }\n\n    private async runInit(): Promise<this> {\n        if (this.isInitialized) return this;\n        // a rerun after a failed startup would re-init the rolled-back plugins\n        if (this.startFailed) throw new SeedcordError(SeedcordErrorCode.LifecycleRestartAfterFailure);\n\n        this.registerPluginTasks();\n\n        if (this.config.errors?.catchProcessErrors ?? true) {\n            Pluggable.liveProcessErrors = registerProcessErrors(this, this[HostShutdown]);\n        }\n\n        const startupSettled: PromiseWithResolvers<void> = Promise.withResolvers();\n        this[HostShutdown].gateOnStartup(startupSettled.promise);\n\n        try {\n            await this[HostStartup].run();\n        } catch (caught) {\n            await this.rollback();\n            throw caught;\n        } finally {\n            startupSettled.resolve();\n        }\n\n        this.isInitialized = true;\n        return this;\n    }\n\n    /** @internal codegen reads this to emit the `Core` augmentation */\n    public get [HostPluginKeys](): readonly string[] {\n        return this.attachments.map((attachment) => attachment.key);\n    }\n\n    /** @internal */\n    protected static reset(host?: object): boolean {\n        if (host !== undefined && Pluggable.liveHost !== host) return false;\n\n        Pluggable.liveShutdown?.removeSignalHandlers();\n        Pluggable.liveShutdown = undefined;\n        Pluggable.liveProcessErrors?.();\n        Pluggable.liveProcessErrors = undefined;\n        Pluggable.liveHost = undefined;\n        Pluggable.isInstantiated = false;\n        return true;\n    }\n\n    /**\n     * Attaches a plugin under `key`. Read the instance back as `core[key]`. `seedcord codegen`\n     * writes the `Core` augmentation that types it there.\n     *\n     * Put one dot in the key to nest the plugin under a group, so `'services.users'` reads back as\n     * `core.services.users`. Each name holds one plugin or one group.\n     *\n     * Startup runs each plugin's `init()` in attach order within its phase.\n     *\n     * Attaching a plugin whose `transport` or `runtime` differs from this host fails to compile.\n     * Your constructor takes `CoreBase` as its first parameter (you don't need to pass it though).\n     * A narrower one fails to compile here.\n     *\n     * @param key - Also the channel the plugin logs on, dots included. Reserved channel names throw.\n     * @param args - Whatever your constructor takes after the host.\n     * @throws A **SeedcordError** if you attach after the bot has started. A taken or reserved key throws too.\n     * So does a plugin that extends `Plugin` from another copy of `@seedcord/core`.\n     * @example\n     * ```ts\n     * seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });\n     * ```\n     */\n    public attach<Key extends string, Ctor extends PluginCtor>(\n        this: this,\n        key: AttachKeyAssert<Key, this>,\n        Plugin: AttachableCtor<Ctor, BotT, BotRt>,\n        ...args: PluginArgs<Ctor>\n    ): this & Attached<Key, InstanceType<Ctor>>;\n    public attach<Key extends string, Ctor extends PluginCtor>(\n        this: this,\n        key: Key,\n        Plugin: Ctor,\n        ...args: PluginArgs<Ctor>\n    ): this & Attached<Key, InstanceType<Ctor>> {\n        if (this.isInitialized) {\n            throw new SeedcordError(SeedcordErrorCode.CorePluginAfterInit);\n        }\n\n        const dot = key.indexOf('.');\n        const head = dot === -1 ? key : key.slice(0, dot);\n\n        // several reserved channels are also members on a host, which the next check would report first\n        if (RESERVED_KEYS.has(head)) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginReservedChannel, [head]);\n        }\n\n        const leaf = dot === -1 ? undefined : key.slice(dot + 1);\n        if (head === '' || leaf === '') {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, 'has an empty part.']);\n        }\n        if (leaf?.includes('.')) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, 'has more than one dot.']);\n        }\n        this.assertFree(head, leaf, key);\n\n        if (!extendsThisCorePlugin(Plugin)) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginFromOtherCore, [Plugin.name]);\n        }\n\n        const instance = new Plugin(this, ...args);\n        pluginLoggerOf(instance).setChannel(key);\n        this.plugins.push(instance);\n        this.attachments.push({ key, instance });\n\n        if (leaf === undefined) {\n            return Object.assign(this, { [key]: instance }) as this & Attached<Key, InstanceType<Ctor>>;\n        }\n\n        this.groupFor(head)[leaf] = instance;\n        return this as this & Attached<Key, InstanceType<Ctor>>;\n    }\n\n    private assertFree(head: string, leaf: string | undefined, key: string): void {\n        if (leaf === undefined) {\n            if (this.groups.has(key)) throw new SeedcordError(SeedcordErrorCode.CorePluginKeyHoldsGroup, [key]);\n            if (key in this) throw new SeedcordError(SeedcordErrorCode.CorePluginKeyExists, [key]);\n            return;\n        }\n\n        const group = this.groups.get(head);\n        if (!group) {\n            if (head in this) throw new SeedcordError(SeedcordErrorCode.CorePluginGroupTaken, [head, key]);\n            return;\n        }\n        if (Object.hasOwn(group, leaf)) throw new SeedcordError(SeedcordErrorCode.CorePluginKeyExists, [key]);\n    }\n\n    private groupFor(head: string): Record<string, PluginLike> {\n        const existing = this.groups.get(head);\n        if (existing) return existing;\n\n        // a null prototype makes a leaf called __proto__ or valueOf an ordinary key\n        const group = Object.create(null) as Record<string, PluginLike>;\n        this.groups.set(head, group);\n        Object.assign(this, { [head]: group });\n        return group;\n    }\n\n    // one combined task per phase keeps plugin inits sequential while the phase's other tasks run concurrently\n    private registerPluginTasks(): void {\n        if (this.pluginTasksRegistered) return;\n        this.pluginTasksRegistered = true;\n\n        const groups = new Map<StartupPhase, Attachment[]>();\n        for (const attachment of this.attachments) {\n            const phase = resolvedLifecycleSpecOf(attachment.instance).init.phase;\n            const group = groups.get(phase) ?? [];\n            group.push(attachment);\n            groups.set(phase, group);\n        }\n\n        for (const [phase, group] of groups) {\n            // Ready inits run in the combined Ready task, before the ready hooks\n            if (phase === StartupPhase.Ready) continue;\n            const budget = group.reduce((sum, a) => sum + resolvedLifecycleSpecOf(a.instance).init.timeout, 0);\n            this.startup.addTask(phase, 'plugins-init', () => this.runInits(group), budget);\n        }\n\n        this.registerReadyTask(groups.get(StartupPhase.Ready) ?? []);\n    }\n\n    private async runInits(group: readonly Attachment[]): Promise<void> {\n        for (const attachment of group) {\n            const { key, instance } = attachment;\n            const spec = resolvedLifecycleSpecOf(instance);\n\n            pluginLoggerOf(instance).utils.initialization(key, 'start');\n            const running = instance.init();\n            try {\n                await withTimeout(`Plugin (${key})`, () => running, spec.init.timeout);\n            } catch (caught) {\n                if (isSeedcordError(caught, undefined, SeedcordErrorCode.LifecycleTaskTimeout)) {\n                    this.disposeWhenInitResolves(attachment, running);\n                }\n                throw caught;\n            }\n            pluginLoggerOf(instance).utils.initialization(key, 'end');\n\n            this.completedInits.add(attachment);\n            if (instance.dispose) this.registerDisposeTask(spec.dispose.phase);\n        }\n    }\n\n    // disposeCompleted skips a plugin missing from completedInits\n    private disposeWhenInitResolves(attachment: Attachment, running: Promise<void>): void {\n        const dispose = attachment.instance.dispose?.bind(attachment.instance);\n        const spec = resolvedLifecycleSpecOf(attachment.instance);\n\n        void running.then(\n            async () => {\n                if (!dispose) return;\n                await withTimeout(`Plugin:${attachment.key}:dispose`, dispose, spec.dispose.timeout).catch(\n                    (caught: unknown) =>\n                        this.pluginLogger.warn(`${attachment.key} dispose failed after a timed-out init`, caught)\n                );\n            },\n            (caught: unknown) => this.pluginLogger.warn(`${attachment.key} init failed after its timeout`, caught)\n        );\n    }\n\n    private registerReadyTask(readyInits: readonly Attachment[]): void {\n        const steps = this.attachments.reduce<{ key: string; run: () => Promise<void>; timeout: number }[]>(\n            (acc, a) => {\n                const ready = a.instance.ready?.bind(a.instance);\n                if (ready) {\n                    acc.push({\n                        key: a.key,\n                        run: ready,\n                        timeout: resolvedLifecycleSpecOf(a.instance).ready.timeout\n                    });\n                }\n                return acc;\n            },\n            []\n        );\n        if (readyInits.length === 0 && steps.length === 0) return;\n\n        const budget =\n            readyInits.reduce((sum, a) => sum + resolvedLifecycleSpecOf(a.instance).init.timeout, 0) +\n            steps.reduce((sum, step) => sum + step.timeout, 0);\n        this.startup.addTask(\n            StartupPhase.Ready,\n            'plugins-ready',\n            async () => {\n                await this.runInits(readyInits);\n                for (const step of steps) {\n                    await withTimeout(`Plugin:${step.key}:ready`, step.run, step.timeout);\n                }\n            },\n            budget\n        );\n    }\n\n    private registerDisposeTask(phase: ShutdownPhase): void {\n        if (this.disposePhases.has(phase)) return;\n        this.disposePhases.add(phase);\n\n        // the budget covers every dispose in this phase because they all run in this one task\n        const budget = this.attachments.reduce((sum, a) => {\n            const spec = resolvedLifecycleSpecOf(a.instance);\n            return a.instance.dispose && spec.dispose.phase === phase ? sum + spec.dispose.timeout : sum;\n        }, 0);\n        this.shutdown.addTask(phase, 'plugins-dispose', () => this.runDisposals(phase), budget);\n    }\n\n    private async runDisposals(phase: ShutdownPhase): Promise<void> {\n        const failures: unknown[] = [];\n        await this.disposeCompleted(phase, (caught) => failures.push(caught));\n        if (failures.length === 1) throw failures[0];\n        if (failures.length > 1) {\n            throw new SeedcordAggregateError(SeedcordErrorCode.PluginDisposeFailures, failures, [failures.length]);\n        }\n    }\n\n    private async disposeCompleted(\n        phase: ShutdownPhase | undefined,\n        onError: (caught: unknown) => void\n    ): Promise<void> {\n        for (const attachment of [...this.attachments].reverse()) {\n            if (!this.completedInits.has(attachment)) continue;\n            const dispose = attachment.instance.dispose?.bind(attachment.instance);\n            if (!dispose) continue;\n            const spec = resolvedLifecycleSpecOf(attachment.instance);\n            if (phase !== undefined && spec.dispose.phase !== phase) continue;\n\n            try {\n                await withTimeout(`Plugin:${attachment.key}:dispose`, dispose, spec.dispose.timeout);\n            } catch (caught) {\n                onError(caught);\n            }\n        }\n    }\n\n    private async rollback(): Promise<void> {\n        this.startFailed = true;\n        // log rollback dispose failures so they do not hide the startup error\n        await this.disposeCompleted(undefined, (caught) => this.pluginLogger.warn('rollback dispose failed', caught));\n        // prevents re-dispose when shutdown runs after rollback\n        this.completedInits.clear();\n    }\n}\n\n// the public `shutdown` field carries addTask alone\nexport function shutdownOf(host: Pick<Pluggable<Transport, Runtime>, typeof HostShutdown>): CoordinatedShutdown {\n    return host[HostShutdown];\n}\n"],"mappings":"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"}

package/dist/{Pluggable-CAteNmfy.d.mts → Pluggable-aRzcpx4e.d.mts}

@@ -1,5 +1,5 @@
 import { i as Bus, n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-DJf12l5T.mjs";
-import { c as PluginLike, d as RuntimeAssert, f as Transport, n as Attached, o as PluginArgs, p as TransportAssert, r as CoreParamAssert, s as PluginCtor, t as AttachKeyAssert, u as Runtime } from "./Plugin-D3wIj0xX.mjs";
+import { c as PluginLike, d as Transport, n as AttachableCtor, o as PluginArgs, r as Attached, s as PluginCtor, t as AttachKeyAssert, u as Runtime } from "./Plugin-D01bBIFo.mjs";
 import { Logger } from "@seedcord/logger";
 import { REST } from "@discordjs/rest";
 import { HostPluginKeys, HostShutdown, HostStartup } from "@seedcord/types/internal";
@@ -138,12 +138,13 @@ declare abstract class Pluggable<BotT extends Transport, BotRt extends Runtime>
    * @param key - Also the channel the plugin logs on, dots included. Reserved channel names throw.
    * @param args - Whatever your constructor takes after the host.
    * @throws A **SeedcordError** if you attach after the bot has started. A taken or reserved key throws too.
+   * So does a plugin that extends `Plugin` from another copy of `@seedcord/core`.
    * @example
    * ```ts
    * seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });
    * ```
    */
-  attach<Key extends string, Ctor extends PluginCtor>(this: this, key: AttachKeyAssert<Key, this>, Plugin: Ctor & TransportAssert<InstanceType<Ctor>, BotT> & RuntimeAssert<InstanceType<Ctor>, BotRt> & CoreParamAssert<Ctor>, ...args: PluginArgs<Ctor>): this & Attached<Key, InstanceType<Ctor>>;
+  attach<Key extends string, Ctor extends PluginCtor>(this: this, key: AttachKeyAssert<Key, this>, Plugin: AttachableCtor<Ctor, BotT, BotRt>, ...args: PluginArgs<Ctor>): this & Attached<Key, InstanceType<Ctor>>;
   private assertFree;
   private groupFor;
   private registerPluginTasks;
@@ -158,4 +159,4 @@ declare abstract class Pluggable<BotT extends Transport, BotRt extends Runtime>
 declare function shutdownOf(host: Pick<Pluggable<Transport, Runtime>, typeof HostShutdown>): CoordinatedShutdown;
 //#endregion
 export { LifecycleTask as a, CoordinatedShutdown as i, shutdownOf as n, CoordinatedStartup as r, Pluggable as t };
-//# sourceMappingURL=Pluggable-CAteNmfy.d.mts.map
+//# sourceMappingURL=Pluggable-aRzcpx4e.d.mts.map

package/dist/{Plugin-BJfRk0s_.mjs → Plugin-CmNW5n6a.mjs}

@@ -109,10 +109,14 @@ function resolvedLifecycleSpecOf(plugin) {
 	return plugin[resolvedSpecSlot];
 }
 /** @internal */
+function extendsThisCorePlugin(ctor) {
+	return ctor.prototype instanceof Plugin;
+}
+/** @internal */
 function pluginLoggerOf(plugin) {
 	return plugin[loggerSlot];
 }
 
 //#endregion
-export { pluginLoggerOf as n, resolvedLifecycleSpecOf as r, Plugin as t };
-//# sourceMappingURL=Plugin-BJfRk0s_.mjs.map
+export { resolvedLifecycleSpecOf as i, extendsThisCorePlugin as n, pluginLoggerOf as r, Plugin as t };
+//# sourceMappingURL=Plugin-CmNW5n6a.mjs.map

package/dist/Plugin-CmNW5n6a.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-CmNW5n6a.mjs","names":[],"sources":["../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordRangeError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '#src/lifecycle/phases';\n\n/**\n * Sets when a plugin's lifecycle methods run. Pass it as the second argument to `super()`. Omit a\n * field to keep its default.\n *\n * @see {@link StartupPhase}\n * @see {@link ShutdownPhase}\n * @example\n * ```ts\n * super(host, { init: { phase: StartupPhase.Login }, dispose: { timeout: 30_000 } });\n * ```\n */\nexport interface PluginLifecycleSpec {\n    /**\n     * Defaults to `StartupPhase.Configuration` and 15000ms. Set the phase to `Ready` and `init()`\n     * runs ahead of every plugin's `ready()`.\n     */\n    init?: { phase?: StartupPhase; timeout?: number };\n    /** `ready()` always runs in `StartupPhase.Ready`. Defaults to a 15000ms timeout. */\n    ready?: { timeout?: number };\n    /** Defaults to `ShutdownPhase.Disconnect` and 10000ms. */\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordRangeError(SeedcordErrorCode.PluginInvalidLifecycleTimeout, [pluginName, field, declared]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '#hmr/devChannel';\n\nimport { RuntimeBrand, TransportBrand } from './brands';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type {\n    TransportOf,\n    PluginOptions,\n    RuntimeOf,\n    Runtime,\n    RuntimeAssert,\n    Transport,\n    TransportAssert\n} from './options';\nimport type { Tail, FrameworkChannel, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord:plugin:spec');\n/** @internal */\nconst loggerSlot = Symbol('seedcord:plugin:logger');\n\n/**\n * Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running\n * bot.\n *\n * Your constructor takes the host first and passes it to `super()`. Add your own parameters after\n * it. `attach()` types them at the call site.\n *\n * @typeParam Opts - Where this plugin may attach, checked only at compile time.\n * @typeParam TCore - The `Core` each transport binds `this.core` to.\n *\n * @example\n * ```ts\n * class Analytics extends Plugin<{ transport: 'gateway' }> {\n *     constructor(\n *         host: CoreBase,\n *         private readonly apiKey: string\n *     ) {\n *         super(host, { init: { phase: StartupPhase.Login } });\n *     }\n *\n *     public async init(): Promise<void> {\n *         await this.connect(this.apiKey);\n *     }\n * }\n *\n * seedcord.attach('analytics', Analytics, apiKey);\n * ```\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    // phantom, never set at runtime.\n    /** @internal */\n    declare readonly [TransportBrand]?: TransportOf<Opts>;\n    /** @internal */\n    declare readonly [RuntimeBrand]?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    readonly [loggerSlot]: Logger;\n\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\n    protected readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[loggerSlot] = this.logger;\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    /**\n     * Runs in `StartupPhase.Configuration` by default.\n     * Move it to a different phase with the {@link PluginLifecycleSpec}.\n     */\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the Ready phase, after every attached plugin's `init()` has resolved. The other Ready\n     * tasks run alongside it, including the http server binding its port.\n     *\n     * Override it when your work needs a logged-in client or a resolved application id.\n     */\n    ready?(): Promise<void>;\n\n    /**\n     * Runs during teardown, in `ShutdownPhase.Disconnect` by default. seedcord skips it when `init()`\n     * has thrown.\n     *\n     * When `init()` outlasts its timeout, seedcord calls this once that `init()` resolves, outside any\n     * shutdown phase. The process must still be alive for that call to happen.\n     */\n    dispose?(): Promise<void>;\n\n    /**\n     * Throws a `SeedcordError` that contains the plugin class name and the reason.\n     *\n     * @param reason - Why the options are invalid.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns relative to the project root\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\n/** @internal */\nexport function extendsThisCorePlugin(ctor: PluginCtor): boolean {\n    return ctor.prototype instanceof Plugin;\n}\n\n/** @internal */\nexport function pluginLoggerOf(plugin: PluginLike): Logger {\n    return plugin[loggerSlot];\n}\n\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<\n    Plugin,\n    'init' | 'ready' | 'dispose' | 'onHmr' | typeof resolvedSpecSlot | typeof loggerSlot\n>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\n/** @internal */\nexport type Attached<Key extends string, Instance> = Key extends `${infer Group}.${infer Leaf}`\n    ? Record<Group, Record<Leaf, Instance>>\n    : Record<Key, Instance>;\n\n// attach writes the key onto the host, so a key like toString would shadow the one on Object.prototype\n// eslint-disable-next-line @typescript-eslint/no-wrapper-object-types -- lint:fix swaps this for `keyof object`, which is never\ntype HostMember<Host> = keyof Host | keyof Object;\n\n// a string argument against an object type renders only as `string is not assignable`\n/** @internal */\nexport type AttachKeyAssert<Key extends string, Host> = Key extends ''\n    ? 'A plugin key needs a name.'\n    : Key extends `${infer Group}.${infer Leaf}`\n      ? Leaf extends `${string}.${string}`\n          ? `'${Key}' has more than one dot. A plugin key takes one dot at most.`\n          : '' extends Group | Leaf\n            ? `'${Key}' has an empty part. Write a group and a plugin name around the dot, like 'services.users'.`\n            : Group extends FrameworkChannel\n              ? `'${Group}' is a channel the framework logs on. Pick another group name.`\n              : Group extends keyof Host\n                ? Host[Group] extends PluginLike\n                    ? `'${Group}' already holds a plugin, so '${Leaf}' cannot nest inside it.`\n                    : Host[Group] extends Record<string, PluginLike>\n                      ? Leaf extends keyof Host[Group]\n                          ? `'${Key}' is already attached.`\n                          : Key\n                      : `'${Group}' is already a member on the bot. Pick another group name.`\n                : Group extends HostMember<Host>\n                  ? `'${Group}' is already a member on the bot. Pick another group name.`\n                  : Key\n      : Key extends FrameworkChannel\n        ? `'${Key}' is a channel the framework logs on. Pick another plugin key.`\n        : Key extends keyof Host\n          ? Host[Key] extends PluginLike\n              ? `'${Key}' is already attached.`\n              : Host[Key] extends Record<string, PluginLike>\n                ? `'${Key}' already holds a group of plugins. Attach this one under a name of its own.`\n                : `'${Key}' is already a member on the bot. Pick another plugin key.`\n          : Key extends HostMember<Host>\n            ? `'${Key}' is already a member on the bot. Pick another plugin key.`\n            : Key;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\ntype CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n\ntype AttachAsserts<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = TransportAssert<\n    InstanceType<Ctor>,\n    BotT\n> &\n    RuntimeAssert<InstanceType<Ctor>, BotRt> &\n    CoreParamAssert<Ctor>;\n\n// typescript can't infer Ctor from a generic class through `Ctor & AttachAsserts`. every assert returns unknown to pass.\n/** @internal */\nexport type AttachableCtor<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> =\n    unknown extends AttachAsserts<Ctor, BotT, BotRt> ? Ctor : AttachAsserts<Ctor, BotT, BotRt>;\n"],"mappings":";;;;;;;AAmCA,MAAM,0BAA0B;AAChC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AAEnC,SAAS,UACL,OACA,UACA,UACA,YACM;CACN,IAAI,aAAa,QAAW,OAAO;CACnC,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,YAAY,GAC1C,MAAM,IAAI,mBAAmB,kBAAkB,+BAA+B;EAAC;EAAY;EAAO;CAAQ,CAAC;CAE/G,OAAO;AACX;;AAGA,SAAgB,qBACZ,MACA,YAC2B;CAC3B,OAAO;EACH,MAAM;GACF,OAAO,MAAM,MAAM;GACnB,SAAS,UAAU,QAAQ,MAAM,MAAM,SAAS,yBAAyB,UAAU;EACvF;EACA,OAAO,EACH,SAAS,UAAU,SAAS,MAAM,OAAO,SAAS,0BAA0B,UAAU,EAC1F;EACA,SAAS;GACL,OAAO,MAAM,SAAS;GACtB,SAAS,UAAU,WAAW,MAAM,SAAS,SAAS,4BAA4B,UAAU;EAChG;CACJ;AACJ;;;;;AC3CA,MAAM,mBAAmB,OAAO,sBAAsB;;AAEtD,MAAM,aAAa,OAAO,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BlD,IAAsB,SAAtB,MAEA;CAiByB;;CATrB,CAAU;;CAEV,CAAU;;CAGV,AAAmB;CAGnB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAI,OAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,cAAc,KAAK;EACxB,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;;;;;CA8BA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAI,cAAc,kBAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,cAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB;;AAGA,SAAgB,sBAAsB,MAA2B;CAC7D,OAAO,KAAK,qBAAqB;AACrC;;AAGA,SAAgB,eAAe,QAA4B;CACvD,OAAO,OAAO;AAClB"}

package/dist/{Plugin-D3wIj0xX.d.mts → Plugin-D01bBIFo.d.mts}

@@ -195,8 +195,10 @@ type HostMember<Host> = keyof Host | keyof Object;
 /** @internal */
 type AttachKeyAssert<Key extends string, Host> = Key extends '' ? 'A plugin key needs a name.' : Key extends `${infer Group}.${infer Leaf}` ? Leaf extends `${string}.${string}` ? `'${Key}' has more than one dot. A plugin key takes one dot at most.` : '' extends Group | Leaf ? `'${Key}' has an empty part. Write a group and a plugin name around the dot, like 'services.users'.` : Group extends FrameworkChannel ? `'${Group}' is a channel the framework logs on. Pick another group name.` : Group extends keyof Host ? Host[Group] extends PluginLike ? `'${Group}' already holds a plugin, so '${Leaf}' cannot nest inside it.` : Host[Group] extends Record<string, PluginLike> ? Leaf extends keyof Host[Group] ? `'${Key}' is already attached.` : Key : `'${Group}' is already a member on the bot. Pick another group name.` : Group extends HostMember<Host> ? `'${Group}' is already a member on the bot. Pick another group name.` : Key : Key extends FrameworkChannel ? `'${Key}' is a channel the framework logs on. Pick another plugin key.` : Key extends keyof Host ? Host[Key] extends PluginLike ? `'${Key}' is already attached.` : Host[Key] extends Record<string, PluginLike> ? `'${Key}' already holds a group of plugins. Attach this one under a name of its own.` : `'${Key}' is already a member on the bot. Pick another plugin key.` : Key extends HostMember<Host> ? `'${Key}' is already a member on the bot. Pick another plugin key.` : Key;
 type CoreParamTooNarrow = Record<'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core', never>;
-/** @internal */
 type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0] ? unknown : CoreParamTooNarrow;
+type AttachAsserts<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = TransportAssert<InstanceType<Ctor>, BotT> & RuntimeAssert<InstanceType<Ctor>, BotRt> & CoreParamAssert<Ctor>;
+/** @internal */
+type AttachableCtor<Ctor extends PluginCtor, BotT extends Transport, BotRt extends Runtime> = unknown extends AttachAsserts<Ctor, BotT, BotRt> ? Ctor : AttachAsserts<Ctor, BotT, BotRt>;
 //#endregion
-export { Plugin as a, PluginLike as c, RuntimeAssert as d, Transport as f, Initializeable as i, PluginOptions as l, PluginLifecycleSpec as m, Attached as n, PluginArgs as o, TransportAssert as p, CoreParamAssert as r, PluginCtor as s, AttachKeyAssert as t, Runtime as u };
-//# sourceMappingURL=Plugin-D3wIj0xX.d.mts.map
+export { Plugin as a, PluginLike as c, Transport as d, PluginLifecycleSpec as f, Initializeable as i, PluginOptions as l, AttachableCtor as n, PluginArgs as o, Attached as r, PluginCtor as s, AttachKeyAssert as t, Runtime as u };
+//# sourceMappingURL=Plugin-D01bBIFo.d.mts.map

package/dist/index.mjs

@@ -1169,7 +1169,7 @@ var CursorSourceBase = class {
 //#endregion
 //#region src/index.ts
 /** Package version */
-const version = "0.9.0";
+const version = "0.9.2";
 
 //#endregion
 export { ArraySourceBase, AutocompleteRoute, BaseHandler, BaseReplySender, BuilderComponent, Bus, ButtonRoute, ChannelMenuRoute, Commands, ContextMenus, Cooldown, CursorSourceBase, CustomId, DispatchContext, DmOnly, Fault, GuildOnly, InteractionKind, MentionableMenuRoute, MessageContextMenuRoute, ModalRoute, Notice, OwnerOnly, PaginatorBase, RegisterCommand, RegisterInteractionMiddleware, RepliableHandler, RequireBotPermissions, RequirePermissions, RequireRole, ResolvedEmoji, RoleMenuRoute, RowComponent, ShutdownPhase, Silence, SlashRoute, StartupPhase, StringMenuRoute, Subscribe, Subscriber, UserContextMenuRoute, UserMenuRoute, WebhookLog, WebhookUrl, and, assertPermissions, decodeFor, defineEffectGate, defineGate, mergeRoles, or, paginate, prefixOf, setCustomIdErrors, version };

package/dist/internal.index.d.mts

@@ -1,7 +1,7 @@
 import { A as UnregisterSubscriber, B as InteractionMiddlewareMetadataKey, C as ReplyMethod, D as RegisterDefaults, E as AckTrace, F as EventMetadataKey, G as Notice, H as MiddlewareKind, I as EventMiddlewareMetadataKey, L as GatedMetadataKey, M as PublishDefault, O as RegisterSubscriber, P as CommandMetadataKey, R as InteractionKind, S as AckState, T as sendTarget, U as SubscribeMetadataKey, V as InteractionRouteKeys, W as WebhookUrlMetadataKey, a as StoredSubscriberCtor, b as ReplyTelemetry, d as DispatchOutcome, i as Bus, j as VerifyWebhooks, k as RegisteredCount, o as SubscriberRegistration, s as busLoggerOf, u as DefaultSubscriptions, w as checkAckLegality, x as reportedWrite, z as InteractionMetadataKey } from "./phases-DJf12l5T.mjs";
 import { A as serializeReply, B as AutocompleteRouteBrand, C as Gate, F as AnyMiddlewareCtor, G as MiddlewareKindsBrand, H as ComponentKindBrand, I as InteractionMiddlewareMetadata, K as SlashRouteBrand, M as EventDispatchResult, P as HandlerResult, Q as BuilderComponent, U as ContextMenuKindBrand, V as ComponentDefsBrand, W as ContextMenuNamesBrand, X as Promisable, Z as IsNever, _ as pickNotice, at as SlashOption, c as FocusedField, ct as ContextMenuKind, dt as NamesFor, i as AutocompletableNames, it as RouteCache, j as DispatchResult, k as SerializedReply, lt as MenuCacheFor, m as PermissionNames, n as PageCursor, nt as CacheFor, o as ChoiceValueOf, ot as SlashRegistry, q as CommandMeta, r as pageCursor, rt as OptionKind, s as EntryFor, st as SlashRouteEntry, t as PAGE_MAX, v as GateFitsWith, w as GateContextBase, z as interactionMiddlewareMetaOf } from "./cursor-BPaPFTic.mjs";
 import { n as CommandBuilder, r as DeployResult } from "./basic-Dng__Ena.mjs";
-import { i as Initializeable, o as PluginArgs, s as PluginCtor } from "./Plugin-D3wIj0xX.mjs";
+import { i as Initializeable, o as PluginArgs, s as PluginCtor } from "./Plugin-D01bBIFo.mjs";
 import { n as contextMenuLeaves, t as ContextMenuLeaves } from "./contextMenuLeaves-COzDYa6c.mjs";
 import "reflect-metadata";
 import { AnyCustomId, DecodedParams } from "@seedcord/custom-id";

package/dist/node-internal.index.d.mts

@@ -1,9 +1,9 @@
 import { i as Bus, n as StartupPhase, r as CoreBase, t as ShutdownPhase } from "./phases-DJf12l5T.mjs";
 import { n as CommandBuilder, r as DeployResult } from "./basic-Dng__Ena.mjs";
 import "./index-BS1hH9Sh.mjs";
-import { i as Initializeable } from "./Plugin-D3wIj0xX.mjs";
+import { i as Initializeable } from "./Plugin-D01bBIFo.mjs";
 import { t as ContextMenuLeaves } from "./contextMenuLeaves-COzDYa6c.mjs";
-import { a as LifecycleTask, i as CoordinatedShutdown, n as shutdownOf } from "./Pluggable-CAteNmfy.mjs";
+import { a as LifecycleTask, i as CoordinatedShutdown, n as shutdownOf } from "./Pluggable-aRzcpx4e.mjs";
 import { Logger } from "@seedcord/logger";
 import { IncomingMessage, ServerResponse } from "node:http";
 import { HealthCheckConfig, HealthCheckOption, HmrAware, HmrUpdateEvent } from "@seedcord/types";

package/dist/node-internal.index.mjs

@@ -5,7 +5,7 @@ import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
 import { t as getDevChannel } from "./devChannel-CQU7hq7Q.mjs";
 import { n as isCommandClass, t as slashRouteLeaves } from "./slashRouteLeaves-DTFHzCKN.mjs";
 import { t as HmrModuleHandler } from "./HmrModuleHandler-9AUfKXRl.mjs";
-import { i as settleWithin, n as shutdownOf, r as assertNodeVersion } from "./Pluggable-BShEwGw9.mjs";
+import { i as settleWithin, n as shutdownOf, r as assertNodeVersion } from "./Pluggable-D-xWcaIv.mjs";
 import { SlashCommandBuilder } from "@discordjs/builders";
 import { Routes } from "discord-api-types/v10";
 import { SeedcordErrorCode, paint } from "@seedcord/errors";

package/dist/node.index.d.mts

@@ -1,2 +1,2 @@
-import { i as CoordinatedShutdown, r as CoordinatedStartup, t as Pluggable } from "./Pluggable-CAteNmfy.mjs";
+import { i as CoordinatedShutdown, r as CoordinatedStartup, t as Pluggable } from "./Pluggable-aRzcpx4e.mjs";
 export { CoordinatedShutdown, CoordinatedStartup, Pluggable };

package/dist/node.index.mjs

@@ -1,5 +1,5 @@
 import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
-import { a as withTimeout, i as settleWithin, t as Pluggable } from "./Pluggable-BShEwGw9.mjs";
+import { a as withTimeout, i as settleWithin, t as Pluggable } from "./Pluggable-D-xWcaIv.mjs";
 import { SeedcordErrorCode, paint } from "@seedcord/errors";
 import { SeedcordAggregateError, SeedcordError, SeedcordRangeError, SeedcordTypeError } from "@seedcord/errors/internal";
 import { Logger } from "@seedcord/logger";

package/dist/plugin.index.d.mts

@@ -1,3 +1,3 @@
-import { a as Plugin, l as PluginOptions, m as PluginLifecycleSpec } from "./Plugin-D3wIj0xX.mjs";
+import { a as Plugin, f as PluginLifecycleSpec, l as PluginOptions } from "./Plugin-D01bBIFo.mjs";
 import { HmrAware, HmrUpdateEvent } from "@seedcord/types";
 export { type HmrAware, type HmrUpdateEvent, Plugin, type PluginLifecycleSpec, type PluginOptions };

package/dist/plugin.index.mjs

@@ -1,3 +1,3 @@
-import { t as Plugin } from "./Plugin-BJfRk0s_.mjs";
+import { t as Plugin } from "./Plugin-CmNW5n6a.mjs";
 
 export { Plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seedcord/core",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "engines": {
     "node": ">=24.11"
   },
@@ -75,19 +75,19 @@
   "dependencies": {
     "@discordjs/builders": "^1.14.1",
     "@discordjs/rest": "^2.6.3",
-    "@seedcord/custom-id": "^0.2.3",
-    "@seedcord/errors": "^0.10.0",
-    "@seedcord/event-emitter": "^0.1.5",
-    "@seedcord/logger": "^0.4.0",
-    "@seedcord/types": "^0.14.0",
-    "@seedcord/utils": "^0.8.13",
+    "@seedcord/custom-id": "^0.2.5",
+    "@seedcord/errors": "^0.11.1",
+    "@seedcord/event-emitter": "^0.1.6",
+    "@seedcord/logger": "^0.4.2",
+    "@seedcord/types": "^0.14.1",
+    "@seedcord/utils": "^0.8.15",
     "discord-api-types": "^0.38.52",
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@seedcord/eslint-config": "^2.2.1",
-    "@seedcord/rate-limiter": "^0.1.9",
-    "@seedcord/tsconfig": "^2.0.3",
+    "@seedcord/eslint-config": "^2.2.2",
+    "@seedcord/rate-limiter": "^0.1.10",
+    "@seedcord/tsconfig": "^2.0.4",
     "@seedcord/tsdown-config": "^2.0.1",
     "@seedcord/vitest-config": "^0.0.1",
     "envapt": "^8.2.2",
@@ -110,5 +110,5 @@
     "test:watch": "vitest dev",
     "coverage": "vitest run --coverage"
   },
-  "readme": "<div align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.seedcord.org/assets/wordmark-dark.webp\" />\n    <img src=\"https://cdn.seedcord.org/assets/wordmark-light.webp\" alt=\"seedcord\" width=\"440\" />\n  </picture>\n</div>\n\n<div align=\"center\">\n  <h3>The whole Discord bot, wired and typed</h3>\n  <a href=\"https://seedcord.org\">Website</a> ·\n  <a href=\"https://guide.seedcord.org\">Guide</a> ·\n  <a href=\"https://docs.seedcord.org\">Reference</a> ·\n  <a href=\"https://discord.gg/DzFxY58WXf\">Discord</a>\n</div>\n\n<br />\n\n<div align=\"center\">\n\n[![npm](https://img.shields.io/npm/v/@seedcord/core?style=flat-square&logo=npm&logoColor=c8341f&label=&labelColor=1f1f1f&color=c8341f)](https://www.npmjs.com/package/@seedcord/core) [![node](https://img.shields.io/node/v/@seedcord/core?style=flat-square&label=node&labelColor=1f1f1f&color=4d7d33)](https://nodejs.org) [![license](https://img.shields.io/npm/l/@seedcord/core?style=flat-square&label=license&labelColor=1f1f1f&color=f8f6e8)](LICENSE)\n\n</div>\n\n## About\n\n`@seedcord/core` is the foundational code both seedcord transports share. Command and context-menu injection, the interaction route decorators, the handler bases, gates, the startup and shutdown phases, and the plugin base all live here.\n\nNothing in it opens a connection to Discord. `@seedcord/gateway` and `@seedcord/http` each bind their own transport into these pieces.\n\nUntil v1.0.0, minor versions can break.\n\n## Installation\n\nYour transport already re-exports all of this.\n\nInstall it directly when you are writing a plugin against the framework:\n\n```sh\npnpm add @seedcord/core\n```\n\n`@seedcord/core/plugin` holds the base a plugin extends.\n"
+  "readme": "<div align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.seedcord.org/assets/wordmark-dark.webp\" />\n    <img src=\"https://cdn.seedcord.org/assets/wordmark-light.webp\" alt=\"seedcord\" width=\"440\" />\n  </picture>\n</div>\n\n<div align=\"center\">\n  <h3>The whole Discord bot, typed end to end</h3>\n  <a href=\"https://seedcord.org\">Website</a> ·\n  <a href=\"https://guide.seedcord.org\">Guide</a> ·\n  <a href=\"https://docs.seedcord.org\">Reference</a> ·\n  <a href=\"https://discord.gg/DzFxY58WXf\">Discord</a>\n</div>\n\n<br />\n\n<div align=\"center\">\n\n[![npm](https://img.shields.io/npm/v/@seedcord/core?style=flat-square&logo=npm&logoColor=c8341f&label=&labelColor=1f1f1f&color=c8341f)](https://www.npmjs.com/package/@seedcord/core) [![node](https://img.shields.io/node/v/@seedcord/core?style=flat-square&label=node&labelColor=1f1f1f&color=4d7d33)](https://nodejs.org) [![license](https://img.shields.io/npm/l/@seedcord/core?style=flat-square&label=license&labelColor=1f1f1f&color=f8f6e8)](LICENSE)\n\n</div>\n\n## About\n\n`@seedcord/core` is the foundational code both seedcord transports share. Command and context-menu injection, the interaction route decorators, the handler bases, gates, the startup and shutdown phases, and the plugin base all live here.\n\nNothing in it opens a connection to Discord. `@seedcord/gateway` and `@seedcord/http` each bind their own transport into these pieces.\n\nUntil v1.0.0, minor versions can break.\n\n## Installation\n\nYour transport already re-exports all of this.\n\nInstall it directly when you are writing a plugin against the framework:\n\n```sh\npnpm add @seedcord/core\n```\n\n`@seedcord/core/plugin` holds the base a plugin extends.\n"
 }

package/dist/Pluggable-BShEwGw9.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"Pluggable-BShEwGw9.mjs","names":[],"sources":["../src/node/Lifecycle/withTimeout.ts","../src/node/assertNodeVersion.ts","../src/node/processErrors.ts","../src/node/Pluggable.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\n// calling start() in here turns its synchronous throw into a rejection\nasync function raceTimer(\n    start: () => Promise<unknown>,\n    timeoutMs: number,\n    onTimeout: (resolve: () => void, reject: (error: unknown) => void) => void\n): Promise<void> {\n    let timer: NodeJS.Timeout | undefined;\n    try {\n        await Promise.race([\n            start(),\n            new Promise<void>((resolve, reject) => {\n                // node's timer can go off before performance.now() reaches timeoutMs\n                const expiresAt = performance.now() + timeoutMs;\n                const tick = (): void => {\n                    const remaining = expiresAt - performance.now();\n                    if (remaining > 0) {\n                        timer = setTimeout(tick, remaining);\n                        return;\n                    }\n                    onTimeout(resolve, reject);\n                };\n                timer = setTimeout(tick, timeoutMs);\n            })\n        ]);\n    } finally {\n        if (timer) clearTimeout(timer);\n    }\n}\n\n// rejects with a LifecycleTaskTimeout when run outlasts the bound\nexport function withTimeout(name: string, run: () => Promise<void>, timeoutMs: number): Promise<void> {\n    return raceTimer(run, timeoutMs, (_, reject) => {\n        reject(new SeedcordError(SeedcordErrorCode.LifecycleTaskTimeout, [name, timeoutMs]));\n    });\n}\n\n// the caller does not get work's rejection\nexport function settleWithin(work: Promise<unknown>, timeoutMs: number): Promise<void> {\n    return raceTimer(\n        () =>\n            work.then(\n                () => undefined,\n                () => undefined\n            ),\n        timeoutMs,\n        (resolve) => resolve()\n    );\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\n// every seedcord package declares engines.node as `>=major` or `>=major.minor`\nconst RANGE = new RegExp(String.raw`^>=(\\d+)(?:\\.(\\d+))?`);\nconst VERSION = /^v?(\\d+)\\.(\\d+)/;\nconst SPACES = /\\s/g;\n\n/** @internal */\nexport function assertNodeVersion(range: string, running: string): void {\n    const required = RANGE.exec(range.replaceAll(SPACES, ''));\n    const current = VERSION.exec(running);\n    if (!required || !current) return;\n\n    const [, requiredMajor, requiredMinor = '0'] = required;\n    const [, currentMajor, currentMinor] = current;\n\n    const meetsRange =\n        Number(currentMajor) > Number(requiredMajor) ||\n        (Number(currentMajor) === Number(requiredMajor) && Number(currentMinor) >= Number(requiredMinor));\n    if (meetsRange) return;\n\n    throw new SeedcordError(SeedcordErrorCode.UnsupportedNodeVersion, [range, running]);\n}\n","import crypto from 'node:crypto';\n\nimport { Logger } from '@seedcord/logger';\n\nimport { asError } from '#stops/asError';\nimport { PublishDefault } from '#subscribers/publishDefault';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { CoordinatedShutdown } from '#node/Lifecycle/CoordinatedShutdown';\n\nconst logger = new Logger('Faults', { channel: 'errors' });\n\n/** @internal */\nexport function registerProcessErrors(core: CoreBase, shutdown: CoordinatedShutdown): () => void {\n    function report(caught: unknown, origin: string): void {\n        const error = asError(caught);\n        const uuid = crypto.randomUUID();\n\n        if (core.config.errors?.errorStack ?? false) logger.error(uuid, error);\n        else logger.error(`${uuid} | ${error.message}`);\n\n        core.bus[PublishDefault]('unknownException', { uuid, dispatchId: null, error, origin });\n    }\n\n    const onRejection = (reason: unknown): void => {\n        report(reason, 'process:unhandledRejection');\n    };\n\n    const onException = (caught: unknown): void => {\n        report(caught, 'process:uncaughtException');\n        // node does not exit on its own once a listener is registered\n        void shutdown.run(1);\n    };\n\n    process.on('unhandledRejection', onRejection);\n    process.on('uncaughtException', onException);\n\n    return () => {\n        process.off('unhandledRejection', onRejection);\n        process.off('uncaughtException', onException);\n    };\n}\n","import { SeedcordErrorCode, isSeedcordError } from '@seedcord/errors';\nimport { SeedcordAggregateError, SeedcordError, SeedcordTypeError } from '@seedcord/errors/internal';\nimport { FRAMEWORK_CHANNELS, Logger } from '@seedcord/logger';\nimport { HostPluginKeys, HostShutdown, HostStartup } from '@seedcord/types/internal';\n\nimport { assertNodeVersion } from '#node/assertNodeVersion';\nimport { StartupPhase } from '#src/lifecycle/phases';\nimport { pluginLoggerOf, resolvedLifecycleSpecOf } from '#src/plugin/Plugin';\n\nimport { withTimeout } from './Lifecycle/withTimeout';\nimport { registerProcessErrors } from './processErrors';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { CoordinatedShutdown } from '#node/Lifecycle/CoordinatedShutdown';\nimport type { CoordinatedStartup } from '#node/Lifecycle/CoordinatedStartup';\nimport type { ShutdownPhase } from '#src/lifecycle/phases';\nimport type { Runtime, RuntimeAssert, Transport, TransportAssert } from '#src/plugin/options';\nimport type {\n    Attached,\n    AttachKeyAssert,\n    CoreParamAssert,\n    PluginArgs,\n    PluginCtor,\n    PluginLike\n} from '#src/plugin/Plugin';\nimport type { Bus } from '#subscribers/Bus';\nimport type { REST } from '@discordjs/rest';\nimport type { Config, IRateLimiter } from '@seedcord/types';\n\ninterface Attachment {\n    readonly key: string;\n    readonly instance: PluginLike;\n}\n\nconst RESERVED_KEYS: ReadonlySet<string> = new Set(FRAMEWORK_CHANNELS);\n\n/**\n * Base class for a plugin host, a transport `Seedcord` class.\n *\n * You attach plugins while configuring the bot. Within one startup phase, their `init()` calls run\n * one after another in attach order.\n */\n// BotRt has no default because RuntimeAssert rejects every plugin once 'edge' is in the union\nexport abstract class Pluggable<BotT extends Transport, BotRt extends Runtime> implements CoreBase {\n    public abstract readonly config: Config;\n    public abstract readonly rest: REST;\n    public abstract readonly applicationId: string;\n    public abstract readonly rateLimiter: IRateLimiter;\n    public abstract readonly bus: Bus;\n\n    /** @internal */\n    readonly [HostShutdown]: CoordinatedShutdown;\n    /** @internal */\n    readonly [HostStartup]: CoordinatedStartup;\n\n    /** Add a task that runs while the bot shuts down. */\n    public readonly shutdown: Pick<CoordinatedShutdown, 'addTask'>;\n\n    /** Add a task that runs while the bot starts. */\n    public readonly startup: Pick<CoordinatedStartup, 'addTask'>;\n\n    protected isInitialized = false;\n    protected startFailed = false;\n    protected readonly plugins: PluginLike[] = [];\n    private readonly groups = new Map<string, Record<string, PluginLike>>();\n\n    private readonly pluginLogger = new Logger('Plugins', { channel: 'plugins' });\n\n    private readonly attachments: Attachment[] = [];\n    private readonly completedInits = new Set<Attachment>();\n    private readonly disposePhases = new Set<ShutdownPhase>();\n    private pluginTasksRegistered = false;\n    private initPromise?: Promise<this> | undefined;\n\n    private static isInstantiated = false;\n    private static liveHost?: object | undefined;\n    private static liveShutdown?: CoordinatedShutdown | undefined;\n    private static liveProcessErrors?: (() => void) | undefined;\n\n    constructor(shutdown: CoordinatedShutdown, startup: CoordinatedStartup) {\n        // a `sideEffects: false` build would drop the same call in the node entry\n        assertNodeVersion(process.env.PACKAGE_NODE_RANGE ?? '', process.version);\n\n        if (Pluggable.isInstantiated) {\n            // signal handlers from the caller's shutdown stay on the process unless dropped here\n            shutdown.removeSignalHandlers();\n            throw new SeedcordError(SeedcordErrorCode.CoreSingletonViolation);\n        }\n\n        Pluggable.isInstantiated = true;\n        Pluggable.liveHost = this;\n        Pluggable.liveShutdown = shutdown;\n        this[HostShutdown] = shutdown;\n        this[HostStartup] = startup;\n        // a getter returning the slot would expose run() and the signal handlers too\n        this.shutdown = { addTask: shutdown.addTask.bind(shutdown) };\n        this.startup = { addTask: startup.addTask.bind(startup) };\n    }\n\n    /** @internal */\n    protected init(): Promise<this> {\n        // clearing the slot on a rejection means a later retry throws its own error\n        this.initPromise ??= this.runInit().catch((caught: unknown) => {\n            this.initPromise = undefined;\n            throw caught;\n        });\n        return this.initPromise;\n    }\n\n    private async runInit(): Promise<this> {\n        if (this.isInitialized) return this;\n        // a rerun after a failed startup would re-init the rolled-back plugins\n        if (this.startFailed) throw new SeedcordError(SeedcordErrorCode.LifecycleRestartAfterFailure);\n\n        this.registerPluginTasks();\n\n        if (this.config.errors?.catchProcessErrors ?? true) {\n            Pluggable.liveProcessErrors = registerProcessErrors(this, this[HostShutdown]);\n        }\n\n        const startupSettled: PromiseWithResolvers<void> = Promise.withResolvers();\n        this[HostShutdown].gateOnStartup(startupSettled.promise);\n\n        try {\n            await this[HostStartup].run();\n        } catch (caught) {\n            await this.rollback();\n            throw caught;\n        } finally {\n            startupSettled.resolve();\n        }\n\n        this.isInitialized = true;\n        return this;\n    }\n\n    /** @internal codegen reads this to emit the `Core` augmentation */\n    public get [HostPluginKeys](): readonly string[] {\n        return this.attachments.map((attachment) => attachment.key);\n    }\n\n    /** @internal */\n    protected static reset(host?: object): boolean {\n        if (host !== undefined && Pluggable.liveHost !== host) return false;\n\n        Pluggable.liveShutdown?.removeSignalHandlers();\n        Pluggable.liveShutdown = undefined;\n        Pluggable.liveProcessErrors?.();\n        Pluggable.liveProcessErrors = undefined;\n        Pluggable.liveHost = undefined;\n        Pluggable.isInstantiated = false;\n        return true;\n    }\n\n    /**\n     * Attaches a plugin under `key`. Read the instance back as `core[key]`. `seedcord codegen`\n     * writes the `Core` augmentation that types it there.\n     *\n     * Put one dot in the key to nest the plugin under a group, so `'services.users'` reads back as\n     * `core.services.users`. Each name holds one plugin or one group.\n     *\n     * Startup runs each plugin's `init()` in attach order within its phase.\n     *\n     * Attaching a plugin whose `transport` or `runtime` differs from this host fails to compile.\n     * Your constructor takes `CoreBase` as its first parameter (you don't need to pass it though).\n     * A narrower one fails to compile here.\n     *\n     * @param key - Also the channel the plugin logs on, dots included. Reserved channel names throw.\n     * @param args - Whatever your constructor takes after the host.\n     * @throws A **SeedcordError** if you attach after the bot has started. A taken or reserved key throws too.\n     * @example\n     * ```ts\n     * seedcord.attach('db', Mongoose, { uri: 'mongodb://...', name: 'seedcord', dir: ... });\n     * ```\n     */\n    public attach<Key extends string, Ctor extends PluginCtor>(\n        this: this,\n        key: AttachKeyAssert<Key, this>,\n        Plugin: Ctor &\n            TransportAssert<InstanceType<Ctor>, BotT> &\n            RuntimeAssert<InstanceType<Ctor>, BotRt> &\n            CoreParamAssert<Ctor>,\n        ...args: PluginArgs<Ctor>\n    ): this & Attached<Key, InstanceType<Ctor>> {\n        if (this.isInitialized) {\n            throw new SeedcordError(SeedcordErrorCode.CorePluginAfterInit);\n        }\n\n        const dot = key.indexOf('.');\n        const head = dot === -1 ? key : key.slice(0, dot);\n\n        // several reserved channels are also members on a host, which the next check would report first\n        if (RESERVED_KEYS.has(head)) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginReservedChannel, [head]);\n        }\n\n        const leaf = dot === -1 ? undefined : key.slice(dot + 1);\n        if (head === '' || leaf === '') {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, 'has an empty part.']);\n        }\n        if (leaf?.includes('.')) {\n            throw new SeedcordTypeError(SeedcordErrorCode.CorePluginKeyMalformed, [key, 'has more than one dot.']);\n        }\n        this.assertFree(head, leaf, key);\n\n        const instance = new Plugin(this, ...args);\n        pluginLoggerOf(instance).setChannel(key);\n        this.plugins.push(instance);\n        this.attachments.push({ key, instance });\n\n        if (leaf === undefined) {\n            return Object.assign(this, { [key]: instance }) as this & Attached<Key, InstanceType<Ctor>>;\n        }\n\n        this.groupFor(head)[leaf] = instance;\n        return this as this & Attached<Key, InstanceType<Ctor>>;\n    }\n\n    private assertFree(head: string, leaf: string | undefined, key: string): void {\n        if (leaf === undefined) {\n            if (this.groups.has(key)) throw new SeedcordError(SeedcordErrorCode.CorePluginKeyHoldsGroup, [key]);\n            if (key in this) throw new SeedcordError(SeedcordErrorCode.CorePluginKeyExists, [key]);\n            return;\n        }\n\n        const group = this.groups.get(head);\n        if (!group) {\n            if (head in this) throw new SeedcordError(SeedcordErrorCode.CorePluginGroupTaken, [head, key]);\n            return;\n        }\n        if (Object.hasOwn(group, leaf)) throw new SeedcordError(SeedcordErrorCode.CorePluginKeyExists, [key]);\n    }\n\n    private groupFor(head: string): Record<string, PluginLike> {\n        const existing = this.groups.get(head);\n        if (existing) return existing;\n\n        // a null prototype makes a leaf called __proto__ or valueOf an ordinary key\n        const group = Object.create(null) as Record<string, PluginLike>;\n        this.groups.set(head, group);\n        Object.assign(this, { [head]: group });\n        return group;\n    }\n\n    // one combined task per phase keeps plugin inits sequential while the phase's other tasks run concurrently\n    private registerPluginTasks(): void {\n        if (this.pluginTasksRegistered) return;\n        this.pluginTasksRegistered = true;\n\n        const groups = new Map<StartupPhase, Attachment[]>();\n        for (const attachment of this.attachments) {\n            const phase = resolvedLifecycleSpecOf(attachment.instance).init.phase;\n            const group = groups.get(phase) ?? [];\n            group.push(attachment);\n            groups.set(phase, group);\n        }\n\n        for (const [phase, group] of groups) {\n            // Ready inits run in the combined Ready task, before the ready hooks\n            if (phase === StartupPhase.Ready) continue;\n            const budget = group.reduce((sum, a) => sum + resolvedLifecycleSpecOf(a.instance).init.timeout, 0);\n            this.startup.addTask(phase, 'plugins-init', () => this.runInits(group), budget);\n        }\n\n        this.registerReadyTask(groups.get(StartupPhase.Ready) ?? []);\n    }\n\n    private async runInits(group: readonly Attachment[]): Promise<void> {\n        for (const attachment of group) {\n            const { key, instance } = attachment;\n            const spec = resolvedLifecycleSpecOf(instance);\n\n            pluginLoggerOf(instance).utils.initialization(key, 'start');\n            const running = instance.init();\n            try {\n                await withTimeout(`Plugin (${key})`, () => running, spec.init.timeout);\n            } catch (caught) {\n                if (isSeedcordError(caught, undefined, SeedcordErrorCode.LifecycleTaskTimeout)) {\n                    this.disposeWhenInitResolves(attachment, running);\n                }\n                throw caught;\n            }\n            pluginLoggerOf(instance).utils.initialization(key, 'end');\n\n            this.completedInits.add(attachment);\n            if (instance.dispose) this.registerDisposeTask(spec.dispose.phase);\n        }\n    }\n\n    // disposeCompleted skips a plugin missing from completedInits\n    private disposeWhenInitResolves(attachment: Attachment, running: Promise<void>): void {\n        const dispose = attachment.instance.dispose?.bind(attachment.instance);\n        const spec = resolvedLifecycleSpecOf(attachment.instance);\n\n        void running.then(\n            async () => {\n                if (!dispose) return;\n                await withTimeout(`Plugin:${attachment.key}:dispose`, dispose, spec.dispose.timeout).catch(\n                    (caught: unknown) =>\n                        this.pluginLogger.warn(`${attachment.key} dispose failed after a timed-out init`, caught)\n                );\n            },\n            (caught: unknown) => this.pluginLogger.warn(`${attachment.key} init failed after its timeout`, caught)\n        );\n    }\n\n    private registerReadyTask(readyInits: readonly Attachment[]): void {\n        const steps = this.attachments.reduce<{ key: string; run: () => Promise<void>; timeout: number }[]>(\n            (acc, a) => {\n                const ready = a.instance.ready?.bind(a.instance);\n                if (ready) {\n                    acc.push({\n                        key: a.key,\n                        run: ready,\n                        timeout: resolvedLifecycleSpecOf(a.instance).ready.timeout\n                    });\n                }\n                return acc;\n            },\n            []\n        );\n        if (readyInits.length === 0 && steps.length === 0) return;\n\n        const budget =\n            readyInits.reduce((sum, a) => sum + resolvedLifecycleSpecOf(a.instance).init.timeout, 0) +\n            steps.reduce((sum, step) => sum + step.timeout, 0);\n        this.startup.addTask(\n            StartupPhase.Ready,\n            'plugins-ready',\n            async () => {\n                await this.runInits(readyInits);\n                for (const step of steps) {\n                    await withTimeout(`Plugin:${step.key}:ready`, step.run, step.timeout);\n                }\n            },\n            budget\n        );\n    }\n\n    private registerDisposeTask(phase: ShutdownPhase): void {\n        if (this.disposePhases.has(phase)) return;\n        this.disposePhases.add(phase);\n\n        // the budget covers every dispose in this phase because they all run in this one task\n        const budget = this.attachments.reduce((sum, a) => {\n            const spec = resolvedLifecycleSpecOf(a.instance);\n            return a.instance.dispose && spec.dispose.phase === phase ? sum + spec.dispose.timeout : sum;\n        }, 0);\n        this.shutdown.addTask(phase, 'plugins-dispose', () => this.runDisposals(phase), budget);\n    }\n\n    private async runDisposals(phase: ShutdownPhase): Promise<void> {\n        const failures: unknown[] = [];\n        await this.disposeCompleted(phase, (caught) => failures.push(caught));\n        if (failures.length === 1) throw failures[0];\n        if (failures.length > 1) {\n            throw new SeedcordAggregateError(SeedcordErrorCode.PluginDisposeFailures, failures, [failures.length]);\n        }\n    }\n\n    private async disposeCompleted(\n        phase: ShutdownPhase | undefined,\n        onError: (caught: unknown) => void\n    ): Promise<void> {\n        for (const attachment of [...this.attachments].reverse()) {\n            if (!this.completedInits.has(attachment)) continue;\n            const dispose = attachment.instance.dispose?.bind(attachment.instance);\n            if (!dispose) continue;\n            const spec = resolvedLifecycleSpecOf(attachment.instance);\n            if (phase !== undefined && spec.dispose.phase !== phase) continue;\n\n            try {\n                await withTimeout(`Plugin:${attachment.key}:dispose`, dispose, spec.dispose.timeout);\n            } catch (caught) {\n                onError(caught);\n            }\n        }\n    }\n\n    private async rollback(): Promise<void> {\n        this.startFailed = true;\n        // log rollback dispose failures so they do not hide the startup error\n        await this.disposeCompleted(undefined, (caught) => this.pluginLogger.warn('rollback dispose failed', caught));\n        // prevents re-dispose when shutdown runs after rollback\n        this.completedInits.clear();\n    }\n}\n\n// the public `shutdown` field carries addTask alone\nexport function shutdownOf(host: Pick<Pluggable<Transport, Runtime>, typeof HostShutdown>): CoordinatedShutdown {\n    return host[HostShutdown];\n}\n"],"mappings":"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"}

package/dist/Plugin-BJfRk0s_.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"Plugin-BJfRk0s_.mjs","names":[],"sources":["../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordRangeError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '#src/lifecycle/phases';\n\n/**\n * Sets when a plugin's lifecycle methods run. Pass it as the second argument to `super()`. Omit a\n * field to keep its default.\n *\n * @see {@link StartupPhase}\n * @see {@link ShutdownPhase}\n * @example\n * ```ts\n * super(host, { init: { phase: StartupPhase.Login }, dispose: { timeout: 30_000 } });\n * ```\n */\nexport interface PluginLifecycleSpec {\n    /**\n     * Defaults to `StartupPhase.Configuration` and 15000ms. Set the phase to `Ready` and `init()`\n     * runs ahead of every plugin's `ready()`.\n     */\n    init?: { phase?: StartupPhase; timeout?: number };\n    /** `ready()` always runs in `StartupPhase.Ready`. Defaults to a 15000ms timeout. */\n    ready?: { timeout?: number };\n    /** Defaults to `ShutdownPhase.Disconnect` and 10000ms. */\n    dispose?: { phase?: ShutdownPhase; timeout?: number };\n}\n\n/** @internal */\nexport interface ResolvedPluginLifecycleSpec {\n    readonly init: { readonly phase: StartupPhase; readonly timeout: number };\n    readonly ready: { readonly timeout: number };\n    readonly dispose: { readonly phase: ShutdownPhase; readonly timeout: number };\n}\n\nconst DEFAULT_INIT_TIMEOUT_MS = 15_000;\nconst DEFAULT_READY_TIMEOUT_MS = 15_000;\nconst DEFAULT_DISPOSE_TIMEOUT_MS = 10_000;\n\nfunction timeoutOf(\n    field: 'init' | 'ready' | 'dispose',\n    declared: number | undefined,\n    fallback: number,\n    pluginName: string\n): number {\n    if (declared === undefined) return fallback;\n    if (!Number.isFinite(declared) || declared <= 0) {\n        throw new SeedcordRangeError(SeedcordErrorCode.PluginInvalidLifecycleTimeout, [pluginName, field, declared]);\n    }\n    return declared;\n}\n\n/** @internal */\nexport function resolveLifecycleSpec(\n    spec: PluginLifecycleSpec | undefined,\n    pluginName: string\n): ResolvedPluginLifecycleSpec {\n    return {\n        init: {\n            phase: spec?.init?.phase ?? StartupPhase.Configuration,\n            timeout: timeoutOf('init', spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)\n        },\n        ready: {\n            timeout: timeoutOf('ready', spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName)\n        },\n        dispose: {\n            phase: spec?.dispose?.phase ?? ShutdownPhase.Disconnect,\n            timeout: timeoutOf('dispose', spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)\n        }\n    };\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\nimport { Logger } from '@seedcord/logger';\n\nimport { getDevChannel } from '#hmr/devChannel';\n\nimport { RuntimeBrand, TransportBrand } from './brands';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { CoreBase } from '#interfaces/CoreBase';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, PluginOptions, RuntimeOf } from './options';\nimport type { Tail, FrameworkChannel, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord:plugin:spec');\n/** @internal */\nconst loggerSlot = Symbol('seedcord:plugin:logger');\n\n/**\n * Base class for a seedcord plugin. Extend it and implement `init()`. `this.core` is the running\n * bot.\n *\n * Your constructor takes the host first and passes it to `super()`. Add your own parameters after\n * it. `attach()` types them at the call site.\n *\n * @typeParam Opts - Where this plugin may attach, checked only at compile time.\n * @typeParam TCore - The `Core` each transport binds `this.core` to.\n *\n * @example\n * ```ts\n * class Analytics extends Plugin<{ transport: 'gateway' }> {\n *     constructor(\n *         host: CoreBase,\n *         private readonly apiKey: string\n *     ) {\n *         super(host, { init: { phase: StartupPhase.Login } });\n *     }\n *\n *     public async init(): Promise<void> {\n *         await this.connect(this.apiKey);\n *     }\n * }\n *\n * seedcord.attach('analytics', Analytics, apiKey);\n * ```\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    // phantom, never set at runtime.\n    /** @internal */\n    declare readonly [TransportBrand]?: TransportOf<Opts>;\n    /** @internal */\n    declare readonly [RuntimeBrand]?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    readonly [loggerSlot]: Logger;\n\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\n    protected readonly logger: Logger;\n\n    // CoreBase here keeps the augmented Core out of ConstructorParameters, which attach reads\n    constructor(\n        private readonly host: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this.logger = new Logger(this.constructor.name);\n        this[loggerSlot] = this.logger;\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\n    }\n\n    /** The host, typed to the transport whose `Plugin` base this class extends. */\n    protected get core(): TCore {\n        // justified: each transport binds TCore to the Core its own host satisfies\n        return this.host as TCore;\n    }\n\n    /**\n     * Runs in `StartupPhase.Configuration` by default.\n     * Move it to a different phase with the {@link PluginLifecycleSpec}.\n     */\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the Ready phase, after every attached plugin's `init()` has resolved. The other Ready\n     * tasks run alongside it, including the http server binding its port.\n     *\n     * Override it when your work needs a logged-in client or a resolved application id.\n     */\n    ready?(): Promise<void>;\n\n    /**\n     * Runs during teardown, in `ShutdownPhase.Disconnect` by default. seedcord skips it when `init()`\n     * has thrown.\n     *\n     * When `init()` outlasts its timeout, seedcord calls this once that `init()` resolves, outside any\n     * shutdown phase. The process must still be alive for that call to happen.\n     */\n    dispose?(): Promise<void>;\n\n    /**\n     * Throws a `SeedcordError` that contains the plugin class name and the reason.\n     *\n     * @param reason - Why the options are invalid.\n     */\n    protected rejectOptions(reason: string): never {\n        throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);\n    }\n\n    /** Override to reload plugin state on an HMR update. */\n    public onHmr(_event: HmrUpdateEvent): Promise<void> {\n        return Promise.resolve();\n    }\n\n    /**\n     * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.\n     * @param patterns - Glob patterns relative to the project root\n     */\n    protected registerCriticalFiles(patterns: string[]): void {\n        getDevChannel()?.send('seedcord:register-critical-files', { patterns });\n    }\n}\n\n/** @internal */\nexport function resolvedLifecycleSpecOf(plugin: PluginLike): ResolvedPluginLifecycleSpec {\n    return plugin[resolvedSpecSlot];\n}\n\n/** @internal */\nexport function pluginLoggerOf(plugin: PluginLike): Logger {\n    return plugin[loggerSlot];\n}\n\nexport type { PluginLifecycleSpec } from './lifecycle';\nexport type { PluginOptions } from './options';\n\n// a bound of Plugin<{}> rejects every plugin that declares an option, since Plugin<A> and Plugin<B>\n// are mutually unassignable. every member here must stay Opts-independent.\n/** @internal */\nexport type PluginLike = Pick<\n    Plugin,\n    'init' | 'ready' | 'dispose' | 'onHmr' | typeof resolvedSpecSlot | typeof loggerSlot\n>;\n\n// a `CoreBase` first parameter rejects a narrowing ctor on its own, and it also collapses\n// `InstanceType<Ctor>` to `PluginLike` at every attach call. CoreParamAssert checks it instead.\n/** @internal */\nexport type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\n/** @internal */\nexport type Attached<Key extends string, Instance> = Key extends `${infer Group}.${infer Leaf}`\n    ? Record<Group, Record<Leaf, Instance>>\n    : Record<Key, Instance>;\n\n// attach writes the key onto the host, so a key like toString would shadow the one on Object.prototype\n// eslint-disable-next-line @typescript-eslint/no-wrapper-object-types -- lint:fix swaps this for `keyof object`, which is never\ntype HostMember<Host> = keyof Host | keyof Object;\n\n// a string argument against an object type renders only as `string is not assignable`\n/** @internal */\nexport type AttachKeyAssert<Key extends string, Host> = Key extends ''\n    ? 'A plugin key needs a name.'\n    : Key extends `${infer Group}.${infer Leaf}`\n      ? Leaf extends `${string}.${string}`\n          ? `'${Key}' has more than one dot. A plugin key takes one dot at most.`\n          : '' extends Group | Leaf\n            ? `'${Key}' has an empty part. Write a group and a plugin name around the dot, like 'services.users'.`\n            : Group extends FrameworkChannel\n              ? `'${Group}' is a channel the framework logs on. Pick another group name.`\n              : Group extends keyof Host\n                ? Host[Group] extends PluginLike\n                    ? `'${Group}' already holds a plugin, so '${Leaf}' cannot nest inside it.`\n                    : Host[Group] extends Record<string, PluginLike>\n                      ? Leaf extends keyof Host[Group]\n                          ? `'${Key}' is already attached.`\n                          : Key\n                      : `'${Group}' is already a member on the bot. Pick another group name.`\n                : Group extends HostMember<Host>\n                  ? `'${Group}' is already a member on the bot. Pick another group name.`\n                  : Key\n      : Key extends FrameworkChannel\n        ? `'${Key}' is a channel the framework logs on. Pick another plugin key.`\n        : Key extends keyof Host\n          ? Host[Key] extends PluginLike\n              ? `'${Key}' is already attached.`\n              : Host[Key] extends Record<string, PluginLike>\n                ? `'${Key}' already holds a group of plugins. Attach this one under a name of its own.`\n                : `'${Key}' is already a member on the bot. Pick another plugin key.`\n          : Key extends HostMember<Host>\n            ? `'${Key}' is already a member on the bot. Pick another plugin key.`\n            : Key;\n\ntype CoreParamTooNarrow = Record<\n    'this plugin constructor must take CoreBase as its first parameter and read the transport Core off this.core',\n    never\n>;\n\n// a narrowed first parameter fails `CoreBase extends Param`\n/** @internal */\nexport type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0]\n    ? unknown\n    : CoreParamTooNarrow;\n"],"mappings":";;;;;;;AAmCA,MAAM,0BAA0B;AAChC,MAAM,2BAA2B;AACjC,MAAM,6BAA6B;AAEnC,SAAS,UACL,OACA,UACA,UACA,YACM;CACN,IAAI,aAAa,QAAW,OAAO;CACnC,IAAI,CAAC,OAAO,SAAS,QAAQ,KAAK,YAAY,GAC1C,MAAM,IAAI,mBAAmB,kBAAkB,+BAA+B;EAAC;EAAY;EAAO;CAAQ,CAAC;CAE/G,OAAO;AACX;;AAGA,SAAgB,qBACZ,MACA,YAC2B;CAC3B,OAAO;EACH,MAAM;GACF,OAAO,MAAM,MAAM;GACnB,SAAS,UAAU,QAAQ,MAAM,MAAM,SAAS,yBAAyB,UAAU;EACvF;EACA,OAAO,EACH,SAAS,UAAU,SAAS,MAAM,OAAO,SAAS,0BAA0B,UAAU,EAC1F;EACA,SAAS;GACL,OAAO,MAAM,SAAS;GACtB,SAAS,UAAU,WAAW,MAAM,SAAS,SAAS,4BAA4B,UAAU;EAChG;CACJ;AACJ;;;;;ACnDA,MAAM,mBAAmB,OAAO,sBAAsB;;AAEtD,MAAM,aAAa,OAAO,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BlD,IAAsB,SAAtB,MAEA;CAiByB;;CATrB,CAAU;;CAEV,CAAU;;CAGV,AAAmB;CAGnB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAI,OAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,cAAc,KAAK;EACxB,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;;;;;CA8BA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAI,cAAc,kBAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,cAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB;;AAGA,SAAgB,eAAe,QAA4B;CACvD,OAAO,OAAO;AAClB"}