@seedcord/core 0.1.0-next.6 → 0.1.0-next.7

package/dist/Plugin-Cgp1a0uQ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-Cgp1a0uQ.cjs","names":["SeedcordError","SeedcordErrorCode","SeedcordError","SeedcordErrorCode","Logger","SeedcordError","SeedcordErrorCode"],"sources":["../src/plugin/context.ts","../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport type { PluginNeed } from './options';\nimport type { Config, Store } from '@seedcord/types';\n\n/**\n * The type each `ctx` capability resolves to. Empty in core, each transport augments it through\n * declaration merging.\n *\n * @example\n * ```typescript\n * declare module '@seedcord/core' {\n *   interface PluginCapabilityTypes {\n *     client: Client;\n *     rest: REST;\n *   }\n * }\n * ```\n */\nexport interface PluginCapabilityTypes {}\n\ntype CapabilityType<Key extends PluginNeed, Fallback> = Key extends keyof PluginCapabilityTypes\n    ? PluginCapabilityTypes[Key]\n    : Fallback;\n\ntype CapabilityValue<TNeeds extends PluginNeed, Key extends PluginNeed, Value> = Key extends TNeeds ? Value : never;\n\n/**\n * The framework surface a plugin reads through `this.ctx`, typed by its declared `needs`.\n *\n * Always available: `config` and `store`. Each capability resolves to its value only when\n * the plugin declared that key, otherwise `never`. The logger comes from `this.logger`.\n *\n * @typeParam TNeeds - The plugin's declared `needs` union.\n */\nexport interface PluginContext<TNeeds extends PluginNeed = never> {\n    readonly config: Config;\n    readonly store: Store<'charge'>;\n    readonly client: CapabilityValue<TNeeds, 'client', CapabilityType<'client', unknown>>;\n    readonly token: CapabilityValue<TNeeds, 'token', string>;\n    /**\n     * The REST client. On http, the client has no token until the Ready phase, so a call from\n     * `init()` sends without a token and returns a 401.\n     */\n    readonly rest: CapabilityValue<TNeeds, 'rest', CapabilityType<'rest', unknown>>;\n}\n\n// the conditional capability types make PluginContext<A> and PluginContext<B> mutually unassignable\n/** @internal */\nexport type StoredPluginContext = Pick<PluginContext, 'config' | 'store'> & {\n    client?: unknown;\n    token?: string | undefined;\n    rest?: unknown;\n};\n\n/**\n * The capability arms a transport supplies from its own Bot/client. `attach` merges them into each\n * plugin's ctx.\n *\n * @internal\n */\nexport interface PluginCapabilities {\n    readonly client?: unknown;\n    readonly token?: string | undefined;\n    readonly rest?: unknown;\n}\n\n/** @internal unset until attach installs the built ctx */\nexport const pluginContextSlot = Symbol('seedcord.plugin.ctx');\n\ninterface ContextHolder {\n    [pluginContextSlot]?: StoredPluginContext;\n}\n\n/** @internal */\nexport function readPluginContext<TNeeds extends PluginNeed>(holder: ContextHolder): PluginContext<TNeeds> {\n    const ctx = holder[pluginContextSlot];\n    if (!ctx) throw new SeedcordError(SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);\n    // safe, finalizePluginContext set the ctx typed for this plugin's declared needs\n    return ctx as PluginContext<TNeeds>;\n}\n\n/** @internal */\nexport function finalizePluginContext<TNeeds extends PluginNeed>(\n    holder: ContextHolder,\n    ctx: PluginContext<TNeeds>\n): void {\n    holder[pluginContextSlot] = ctx;\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '@src/lifecycle/phases';\n\n/**\n * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base\n * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.\n */\nexport interface PluginLifecycleSpec {\n    init?: { phase?: StartupPhase; timeout?: number };\n    ready?: { timeout?: number };\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 SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [\n            pluginName,\n            `lifecycle ${field}.timeout must be a positive number of milliseconds`\n        ]);\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 { pluginContextSlot, readPluginContext } from './context';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { PluginContext, StoredPluginContext } from './context';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, NeedsOf, PluginOptions, RuntimeOf } from './options';\nimport type { CoreBase } from '@interfaces/CoreBase';\nimport type { Tail, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord.plugin.spec');\n\n/**\n * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,\n * implements `init()`, and reads the framework surface through `this.ctx`.\n *\n * @typeParam Opts - The plugin's declared {@link PluginOptions}.\n * @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    /** @internal phantom, never set at runtime */\n    declare readonly __transport?: TransportOf<Opts>;\n    /** @internal phantom, never set at runtime */\n    declare readonly __runtime?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    [pluginContextSlot]?: StoredPluginContext;\n\n    /** Logs under the plugin's class name, on the channel its attach key names. */\n    public 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[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    /** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */\n    protected get ctx(): PluginContext<NeedsOf<Opts>> {\n        return readPluginContext<NeedsOf<Opts>>(this);\n    }\n\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,\n     * and the http host runs its server-bind and health tasks in the same phase.\n     */\n    ready?(): Promise<void>;\n\n    /** Runs during teardown, only when `init()` resolved. */\n    dispose?(): Promise<void>;\n\n    /**\n     * Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the\n     * plugin class 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\nexport type { PluginContext, PluginCapabilityTypes } from './context';\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' | 'logger' | 'onHmr' | typeof resolvedSpecSlot | typeof pluginContextSlot\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\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\nexport { finalizePluginContext } from './context';\n"],"mappings":";;;;;;;;AAqEA,MAAa,oBAAoB,OAAO,qBAAqB;;AAO7D,SAAgB,kBAA6C,QAA8C;CACvG,MAAM,MAAM,OAAO;CACnB,IAAI,CAAC,KAAK,MAAM,IAAIA,wCAAcC,mCAAkB,yBAAyB,CAAC,OAAO,YAAY,IAAI,CAAC;CAEtG,OAAO;AACX;;AAGA,SAAgB,sBACZ,QACA,KACI;CACJ,OAAO,qBAAqB;AAChC;;;;ACnEA,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,IAAIC,wCAAcC,mCAAkB,uBAAuB,CAC7D,YACA,aAAa,MAAM,mDACvB,CAAC;CAEL,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;;;;;ACxCA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAgByB;;CATrB,CAAU;;CAEV,CAAC;;CAGD,AAAgB;CAGhB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAIC,wBAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;CAGA,IAAc,MAAoC;EAC9C,OAAO,kBAAiC,IAAI;CAChD;;;;;;;CAmBA,AAAU,cAAc,QAAuB;EAC3C,MAAM,IAAIC,wCAAcC,mCAAkB,uBAAuB,CAAC,KAAK,YAAY,MAAM,MAAM,CAAC;CACpG;;CAGA,AAAO,MAAM,QAAuC;EAChD,OAAO,QAAQ,QAAQ;CAC3B;;;;;CAMA,AAAU,sBAAsB,UAA0B;EACtD,iCAAc,CAAC,EAAE,KAAK,oCAAoC,EAAE,SAAS,CAAC;CAC1E;AACJ;;AAGA,SAAgB,wBAAwB,QAAiD;CACrF,OAAO,OAAO;AAClB"}

package/dist/{Plugin-PcdPjAzc.mjs → Plugin-j9GYdroS.mjs}

@@ -2,6 +2,7 @@ import { n as StartupPhase, t as ShutdownPhase } from "./phases-BfpAG6w3.mjs";
 import { t as getDevChannel } from "./devChannel-CQU7hq7Q.mjs";
 import { SeedcordErrorCode } from "@seedcord/errors";
 import { SeedcordError } from "@seedcord/errors/internal";
+import { Logger } from "@seedcord/logger";
 
 //#region src/plugin/context.ts
 /** @internal unset until attach installs the built ctx */
@@ -51,17 +52,25 @@ const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
 * implements `init()`, and reads the framework surface through `this.ctx`.
 *
 * @typeParam Opts - The plugin's declared {@link PluginOptions}.
+* @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.
 */
 var Plugin = class {
-	pluggable;
+	host;
 	/** @internal */
 	[resolvedSpecSlot];
 	/** @internal */
 	[pluginContextSlot];
-	constructor(pluggable, spec) {
-		this.pluggable = pluggable;
+	/** Logs under the plugin's class name, on the channel its attach key names. */
+	logger;
+	constructor(host, spec) {
+		this.host = host;
+		this.logger = new Logger(this.constructor.name);
 		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
 	}
+	/** The host, typed to the transport whose `Plugin` base this class extends. */
+	get core() {
+		return this.host;
+	}
 	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
 	get ctx() {
 		return readPluginContext(this);
@@ -94,4 +103,4 @@ function resolvedLifecycleSpecOf(plugin) {
 
 //#endregion
 export { resolvedLifecycleSpecOf as n, finalizePluginContext as r, Plugin as t };
-//# sourceMappingURL=Plugin-PcdPjAzc.mjs.map
+//# sourceMappingURL=Plugin-j9GYdroS.mjs.map

package/dist/Plugin-j9GYdroS.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-j9GYdroS.mjs","names":[],"sources":["../src/plugin/context.ts","../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport type { PluginNeed } from './options';\nimport type { Config, Store } from '@seedcord/types';\n\n/**\n * The type each `ctx` capability resolves to. Empty in core, each transport augments it through\n * declaration merging.\n *\n * @example\n * ```typescript\n * declare module '@seedcord/core' {\n *   interface PluginCapabilityTypes {\n *     client: Client;\n *     rest: REST;\n *   }\n * }\n * ```\n */\nexport interface PluginCapabilityTypes {}\n\ntype CapabilityType<Key extends PluginNeed, Fallback> = Key extends keyof PluginCapabilityTypes\n    ? PluginCapabilityTypes[Key]\n    : Fallback;\n\ntype CapabilityValue<TNeeds extends PluginNeed, Key extends PluginNeed, Value> = Key extends TNeeds ? Value : never;\n\n/**\n * The framework surface a plugin reads through `this.ctx`, typed by its declared `needs`.\n *\n * Always available: `config` and `store`. Each capability resolves to its value only when\n * the plugin declared that key, otherwise `never`. The logger comes from `this.logger`.\n *\n * @typeParam TNeeds - The plugin's declared `needs` union.\n */\nexport interface PluginContext<TNeeds extends PluginNeed = never> {\n    readonly config: Config;\n    readonly store: Store<'charge'>;\n    readonly client: CapabilityValue<TNeeds, 'client', CapabilityType<'client', unknown>>;\n    readonly token: CapabilityValue<TNeeds, 'token', string>;\n    /**\n     * The REST client. On http, the client has no token until the Ready phase, so a call from\n     * `init()` sends without a token and returns a 401.\n     */\n    readonly rest: CapabilityValue<TNeeds, 'rest', CapabilityType<'rest', unknown>>;\n}\n\n// the conditional capability types make PluginContext<A> and PluginContext<B> mutually unassignable\n/** @internal */\nexport type StoredPluginContext = Pick<PluginContext, 'config' | 'store'> & {\n    client?: unknown;\n    token?: string | undefined;\n    rest?: unknown;\n};\n\n/**\n * The capability arms a transport supplies from its own Bot/client. `attach` merges them into each\n * plugin's ctx.\n *\n * @internal\n */\nexport interface PluginCapabilities {\n    readonly client?: unknown;\n    readonly token?: string | undefined;\n    readonly rest?: unknown;\n}\n\n/** @internal unset until attach installs the built ctx */\nexport const pluginContextSlot = Symbol('seedcord.plugin.ctx');\n\ninterface ContextHolder {\n    [pluginContextSlot]?: StoredPluginContext;\n}\n\n/** @internal */\nexport function readPluginContext<TNeeds extends PluginNeed>(holder: ContextHolder): PluginContext<TNeeds> {\n    const ctx = holder[pluginContextSlot];\n    if (!ctx) throw new SeedcordError(SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);\n    // safe, finalizePluginContext set the ctx typed for this plugin's declared needs\n    return ctx as PluginContext<TNeeds>;\n}\n\n/** @internal */\nexport function finalizePluginContext<TNeeds extends PluginNeed>(\n    holder: ContextHolder,\n    ctx: PluginContext<TNeeds>\n): void {\n    holder[pluginContextSlot] = ctx;\n}\n","import { SeedcordErrorCode } from '@seedcord/errors';\nimport { SeedcordError } from '@seedcord/errors/internal';\n\nimport { ShutdownPhase, StartupPhase } from '@src/lifecycle/phases';\n\n/**\n * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base\n * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.\n */\nexport interface PluginLifecycleSpec {\n    init?: { phase?: StartupPhase; timeout?: number };\n    ready?: { timeout?: number };\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 SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [\n            pluginName,\n            `lifecycle ${field}.timeout must be a positive number of milliseconds`\n        ]);\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 { pluginContextSlot, readPluginContext } from './context';\nimport { resolveLifecycleSpec } from './lifecycle';\n\nimport type { PluginContext, StoredPluginContext } from './context';\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, NeedsOf, PluginOptions, RuntimeOf } from './options';\nimport type { CoreBase } from '@interfaces/CoreBase';\nimport type { Tail, HmrAware, HmrUpdateEvent } from '@seedcord/types';\n\nexport interface Initializeable {\n    init(): Promise<void>;\n}\n\n/** @internal */\nconst resolvedSpecSlot = Symbol('seedcord.plugin.spec');\n\n/**\n * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,\n * implements `init()`, and reads the framework surface through `this.ctx`.\n *\n * @typeParam Opts - The plugin's declared {@link PluginOptions}.\n * @typeParam TCore - The host type `this.core` resolves to. Each transport binds it to its own `Core`.\n */\nexport abstract class Plugin<Opts extends PluginOptions = {}, TCore extends CoreBase = CoreBase>\n    implements Initializeable, HmrAware\n{\n    /** @internal phantom, never set at runtime */\n    declare readonly __transport?: TransportOf<Opts>;\n    /** @internal phantom, never set at runtime */\n    declare readonly __runtime?: RuntimeOf<Opts>;\n\n    /** @internal */\n    readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;\n    /** @internal */\n    [pluginContextSlot]?: StoredPluginContext;\n\n    /** Logs under the plugin's class name, on the channel its attach key names. */\n    public 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[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    /** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */\n    protected get ctx(): PluginContext<NeedsOf<Opts>> {\n        return readPluginContext<NeedsOf<Opts>>(this);\n    }\n\n    abstract init(): Promise<void>;\n\n    /**\n     * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,\n     * and the http host runs its server-bind and health tasks in the same phase.\n     */\n    ready?(): Promise<void>;\n\n    /** Runs during teardown, only when `init()` resolved. */\n    dispose?(): Promise<void>;\n\n    /**\n     * Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the\n     * plugin class 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\nexport type { PluginContext, PluginCapabilityTypes } from './context';\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' | 'logger' | 'onHmr' | typeof resolvedSpecSlot | typeof pluginContextSlot\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\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\nexport { finalizePluginContext } from './context';\n"],"mappings":";;;;;;;;AAqEA,MAAa,oBAAoB,OAAO,qBAAqB;;AAO7D,SAAgB,kBAA6C,QAA8C;CACvG,MAAM,MAAM,OAAO;CACnB,IAAI,CAAC,KAAK,MAAM,IAAI,cAAc,kBAAkB,yBAAyB,CAAC,OAAO,YAAY,IAAI,CAAC;CAEtG,OAAO;AACX;;AAGA,SAAgB,sBACZ,QACA,KACI;CACJ,OAAO,qBAAqB;AAChC;;;;ACnEA,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,cAAc,kBAAkB,uBAAuB,CAC7D,YACA,aAAa,MAAM,mDACvB,CAAC;CAEL,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;;;;;ACxCA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAgByB;;CATrB,CAAU;;CAEV,CAAC;;CAGD,AAAgB;CAGhB,YACI,AAAiB,MACjB,MACF;EAFmB;EAGjB,KAAK,SAAS,IAAI,OAAO,KAAK,YAAY,IAAI;EAC9C,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;CAGA,IAAc,OAAc;EAExB,OAAO,KAAK;CAChB;;CAGA,IAAc,MAAoC;EAC9C,OAAO,kBAAiC,IAAI;CAChD;;;;;;;CAmBA,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"}

package/dist/{permissions-DSW_EZfN.cjs → Silence-DiP95iwD.cjs}

@@ -1,3 +1,4 @@
+const require_publishDefault = require('./publishDefault-l0NQ-SHo.cjs');
 require("reflect-metadata");
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
@@ -5,43 +6,6 @@ let discord_api_types_v10 = require("discord-api-types/v10");
 let _discordjs_builders = require("@discordjs/builders");
 let _seedcord_utils = require("@seedcord/utils");
 
-//#region src/metadataKeys.ts
-let InteractionRoutes = /* @__PURE__ */ function(InteractionRoutes) {
-	InteractionRoutes["Slash"] = "slash";
-	InteractionRoutes["Button"] = "button";
-	InteractionRoutes["Modal"] = "modal";
-	InteractionRoutes["StringMenu"] = "stringMenu";
-	InteractionRoutes["UserMenu"] = "userMenu";
-	InteractionRoutes["RoleMenu"] = "roleMenu";
-	InteractionRoutes["ChannelMenu"] = "channelMenu";
-	InteractionRoutes["MentionableMenu"] = "mentionableMenu";
-	InteractionRoutes["MessageContextMenu"] = "messageContextMenu";
-	InteractionRoutes["UserContextMenu"] = "userContextMenu";
-	InteractionRoutes["Autocomplete"] = "autocomplete";
-	return InteractionRoutes;
-}({});
-const InteractionMetadataKey = Symbol("seedcord:interaction:metadata");
-const InteractionRouteKeys = {
-	["slash"]: Symbol("seedcord:interaction:slash"),
-	["button"]: Symbol("seedcord:interaction:button"),
-	["modal"]: Symbol("seedcord:interaction:modal"),
-	["stringMenu"]: Symbol("seedcord:interaction:stringMenu"),
-	["userMenu"]: Symbol("seedcord:interaction:userMenu"),
-	["roleMenu"]: Symbol("seedcord:interaction:roleMenu"),
-	["channelMenu"]: Symbol("seedcord:interaction:channelMenu"),
-	["mentionableMenu"]: Symbol("seedcord:interaction:mentionableMenu"),
-	["messageContextMenu"]: Symbol("seedcord:interaction:messageContextMenu"),
-	["userContextMenu"]: Symbol("seedcord:interaction:userContextMenu"),
-	["autocomplete"]: Symbol("seedcord:interaction:autocomplete")
-};
-const MiddlewareMetadataKey = Symbol("seedcord:middleware:metadata");
-const EventMetadataKey = Symbol("seedcord:event:metadata");
-const CommandMetadataKey = Symbol("seedcord:command:metadata");
-const GatedMetadataKey = Symbol("seedcord:gated:metadata");
-const SubscribeMetadataKey = Symbol("seedcord:subscribe:metadata");
-const WebhookUrlMetadataKey = Symbol("seedcord:webhookUrl:metadata");
-
-//#endregion
 //#region src/stops/Notice.ts
 /**
 * Base class for a user-facing refusal or a reported fault.
@@ -107,209 +71,13 @@ var Notice = class extends Error {
 	}
 };
 
-//#endregion
-//#region src/components/botColorHolder.ts
-const DEFAULT_COLOR = "Default";
-let current = DEFAULT_COLOR;
-function setBotColor(color) {
-	current = color ?? DEFAULT_COLOR;
-}
-function getBotColor() {
-	return current;
-}
-
-//#endregion
-//#region src/components/builderTypes.ts
-/**
-* Available Discord.js builder classes for use with BuilderComponent for commands, embeds, modals, etc.
-*
-* @internal
-*/
-const BuilderTypes = {
-	command: _discordjs_builders.SlashCommandBuilder,
-	context_menu: _discordjs_builders.ContextMenuCommandBuilder,
-	subcommand: _discordjs_builders.SlashCommandSubcommandBuilder,
-	group: _discordjs_builders.SlashCommandSubcommandGroupBuilder,
-	embed: _discordjs_builders.EmbedBuilder,
-	modal: _discordjs_builders.ModalBuilder,
-	label: _discordjs_builders.LabelBuilder,
-	text_input: _discordjs_builders.TextInputBuilder,
-	file_upload: _discordjs_builders.FileUploadBuilder,
-	checkbox: _discordjs_builders.CheckboxBuilder,
-	checkbox_group: _discordjs_builders.CheckboxGroupBuilder,
-	checkbox_group_option: _discordjs_builders.CheckboxGroupOptionBuilder,
-	radio_group: _discordjs_builders.RadioGroupBuilder,
-	radio_group_option: _discordjs_builders.RadioGroupOptionBuilder,
-	button: _discordjs_builders.ButtonBuilder,
-	menu_string: _discordjs_builders.StringSelectMenuBuilder,
-	menu_option_string: _discordjs_builders.StringSelectMenuOptionBuilder,
-	menu_user: _discordjs_builders.UserSelectMenuBuilder,
-	menu_channel: _discordjs_builders.ChannelSelectMenuBuilder,
-	menu_mentionable: _discordjs_builders.MentionableSelectMenuBuilder,
-	menu_role: _discordjs_builders.RoleSelectMenuBuilder,
-	container: _discordjs_builders.ContainerBuilder,
-	text_display: _discordjs_builders.TextDisplayBuilder,
-	file: _discordjs_builders.FileBuilder,
-	media: _discordjs_builders.MediaGalleryBuilder,
-	section: _discordjs_builders.SectionBuilder,
-	separator: _discordjs_builders.SeparatorBuilder
-};
-/**
-* Available Discord.js action row classes for use with RowComponent for Select Menus and Buttons
-*
-* @internal
-*/
-const RowTypes = {
-	button: _discordjs_builders.ActionRowBuilder,
-	menu_string: _discordjs_builders.ActionRowBuilder,
-	menu_user: _discordjs_builders.ActionRowBuilder,
-	menu_channel: _discordjs_builders.ActionRowBuilder,
-	menu_mentionable: _discordjs_builders.ActionRowBuilder,
-	menu_role: _discordjs_builders.ActionRowBuilder
-};
-
-//#endregion
-//#region src/components/colors.ts
-const Colors = {
-	Aqua: 1752220,
-	Blue: 3447003,
-	Blurple: 5793266,
-	DarkAqua: 1146986,
-	DarkBlue: 2123412,
-	DarkButNotBlack: 2895667,
-	DarkerGrey: 8359053,
-	DarkGold: 12745742,
-	DarkGreen: 2067276,
-	DarkGrey: 9936031,
-	DarkNavy: 2899536,
-	DarkOrange: 11027200,
-	DarkPurple: 7419530,
-	DarkRed: 10038562,
-	DarkVividPink: 11342935,
-	Default: 0,
-	Fuchsia: 15418782,
-	Gold: 15844367,
-	Green: 5763719,
-	Grey: 9807270,
-	Greyple: 10070709,
-	LightGrey: 12370112,
-	LuminousVividPink: 15277667,
-	Navy: 3426654,
-	NotQuiteBlack: 2303786,
-	Orange: 15105570,
-	Purple: 10181046,
-	Red: 15548997,
-	White: 16777215,
-	Yellow: 16705372
-};
-
-//#endregion
-//#region src/components/resolveColor.ts
-const MAX_COLOR = 16777215;
-const RED_SHIFT = 16;
-const GREEN_SHIFT = 8;
-const palette = Colors;
-/**
-* Resolves a {@link BotColor} to the integer Discord expects.
-*
-* Ported from discord.js (Apache-2.0), `resolveColor` in src/util/Util.js.
-*/
-function resolveColor(color) {
-	let resolved;
-	if (typeof color === "string") {
-		if (color === "Random") return Math.floor(Math.random() * 16777216);
-		if (color === "Default") return 0;
-		if (/^#?[\da-f]{6}$/i.test(color)) return Number.parseInt(color.replace("#", ""), 16);
-		resolved = palette[color];
-	} else if (typeof color === "number") resolved = color;
-	else resolved = (color[0] << RED_SHIFT) + (color[1] << GREEN_SHIFT) + color[2];
-	if (resolved === void 0 || !Number.isSafeInteger(resolved)) throw new _seedcord_errors_internal.SeedcordTypeError(_seedcord_errors.SeedcordErrorCode.ColorUnresolvable, [JSON.stringify(color)]);
-	if (resolved < 0 || resolved > MAX_COLOR) throw new _seedcord_errors_internal.SeedcordRangeError(_seedcord_errors.SeedcordErrorCode.ColorOutOfRange);
-	return resolved;
-}
-
-//#endregion
-//#region src/components/Component.ts
-/**
-* Base class for Discord component wrappers.
-*
-* @typeParam TComponent - The Discord.js component type being wrapped
-*
-* @internal
-*/
-var BaseComponent = class {
-	_component;
-	constructor(ComponentClass) {
-		this._component = new ComponentClass();
-	}
-	/**
-	* The wrapped builder, for calling Discord.js methods like setTitle() and setDescription() inside a subclass.
-	*
-	* @example this.instance.setTitle('My Modal')
-	*/
-	get instance() {
-		return this._component;
-	}
-};
-/**
-* Base class for Discord.js builder components
-*
-* Wraps Discord.js builders (SlashCommandBuilder, EmbedBuilder, etc.) with
-* Seedcord-specific defaults and helper methods.
-*
-* @typeParam BuilderKey - The type of Discord.js builder being wrapped
-*/
-var BuilderComponent = class extends BaseComponent {
-	type;
-	colorApplied = false;
-	constructor(type) {
-		const ComponentClass = BuilderTypes[type];
-		super(ComponentClass);
-		this.type = type;
-		if (this.instance instanceof _discordjs_builders.SlashCommandBuilder || this.instance instanceof _discordjs_builders.ContextMenuCommandBuilder) this.instance.setContexts(discord_api_types_v10.InteractionContextType.Guild);
-	}
-	get component() {
-		this.applyBotColor();
-		return this.instance;
-	}
-	applyBotColor() {
-		if (this.colorApplied) return;
-		this.colorApplied = true;
-		const color = getBotColor();
-		if (this.instance instanceof _discordjs_builders.EmbedBuilder) {
-			if (this.instance.data.color === void 0) this.instance.setColor(resolveColor(color));
-		} else if (this.instance instanceof _discordjs_builders.ContainerBuilder) {
-			const accent = this.instance.data.accent_color;
-			if (accent === null || accent === void 0) this.instance.setAccentColor(color === "Default" ? void 0 : resolveColor(color));
-		}
-	}
-};
-/**
-* Base class for Discord action row components
-*
-* Wraps Discord.js action row builder with Seedcord-specific defaults and helper methods.
-*
-* @typeParam RowKey - The Discord.js action row type being wrapped
-*/
-var RowComponent = class extends BaseComponent {
-	type;
-	constructor(type) {
-		const ComponentClass = RowTypes[type];
-		super(ComponentClass);
-		this.type = type;
-	}
-	get component() {
-		return this.instance;
-	}
-};
-
 //#endregion
 //#region src/stops/NoticeCard.ts
 /**
 * Built fresh inside a {@link Notice}'s `render` to back its ComponentsV2 reply. The title renders as
 * an h3 line with the description on the next line.
 */
-var NoticeCard = class extends BuilderComponent {
+var NoticeCard = class extends require_publishDefault.BuilderComponent {
 	constructor(description, title = "Cannot Proceed") {
 		super("container");
 		this.instance.addTextDisplayComponents(new _discordjs_builders.TextDisplayBuilder().setContent(`### ${title}\n${description}`));
@@ -772,19 +540,19 @@ function areRoutes(routes) {
 */
 function interactionRoutesOf(constructor) {
 	const pairs = [];
-	for (const route of Object.values(InteractionRoutes)) {
-		const meta = Reflect.getMetadata(InteractionRouteKeys[route], constructor);
+	for (const route of Object.values(require_publishDefault.InteractionRoutes)) {
+		const meta = Reflect.getMetadata(require_publishDefault.InteractionRouteKeys[route], constructor);
 		if (areRoutes(meta)) pairs.push([route, meta]);
 	}
 	return pairs;
 }
 function storeInteractionRoute(route, routes, constructor) {
-	const key = InteractionRouteKeys[route];
+	const key = require_publishDefault.InteractionRouteKeys[route];
 	const saved = Reflect.getMetadata(key, constructor);
 	const existing = areRoutes(saved) ? saved : [];
 	const toStore = typeof routes === "string" ? [routes] : routes;
 	Reflect.defineMetadata(key, [...existing, ...toStore], constructor);
-	Reflect.defineMetadata(InteractionMetadataKey, true, constructor);
+	Reflect.defineMetadata(require_publishDefault.InteractionMetadataKey, true, constructor);
 }
 function storeComponentRoute(route, defs, constructor) {
 	storeInteractionRoute(route, defs.map((def) => def.prefix), constructor);
@@ -1067,18 +835,35 @@ function RequireRole(roleId, options) {
 }
 
 //#endregion
-Object.defineProperty(exports, 'BuilderComponent', {
-  enumerable: true,
-  get: function () {
-    return BuilderComponent;
-  }
-});
-Object.defineProperty(exports, 'CommandMetadataKey', {
-  enumerable: true,
-  get: function () {
-    return CommandMetadataKey;
-  }
-});
+//#region src/stops/Silence.ts
+/**
+* Throw to stop a handler with no reply and no report.
+*
+* The framework boundary catches `Silence` before {@link Notice}, makes zero Discord calls, and stops.
+* Ideally you'd only throw this in `EventHandlers` (or `Gates` for those), because it doesn't make sense to
+* leave the user with no reply for an interaction.
+*
+* @example
+* ```ts
+* import { Silence } from '@seedcord/gateway';
+*
+* // before any reply or defer, drop the interaction with no reply and no report
+* if (await isBlacklisted(interaction.user.id)) throw new Silence('blacklisted user');
+* ```
+*/
+var Silence = class extends Error {
+	reason;
+	/**
+	* @param reason - Optional note written only to a debug log, never shown to the user or reported.
+	*/
+	constructor(reason) {
+		super(reason ?? "Silence");
+		this.reason = reason;
+		Error.captureStackTrace(this, this.constructor);
+	}
+};
+
+//#endregion
 Object.defineProperty(exports, 'ComponentDefsKey', {
   enumerable: true,
   get: function () {
@@ -1091,48 +876,12 @@ Object.defineProperty(exports, 'CustomId', {
     return CustomId;
   }
 });
-Object.defineProperty(exports, 'EventMetadataKey', {
-  enumerable: true,
-  get: function () {
-    return EventMetadataKey;
-  }
-});
 Object.defineProperty(exports, 'GateNotice', {
   enumerable: true,
   get: function () {
     return GateNotice;
   }
 });
-Object.defineProperty(exports, 'GatedMetadataKey', {
-  enumerable: true,
-  get: function () {
-    return GatedMetadataKey;
-  }
-});
-Object.defineProperty(exports, 'InteractionMetadataKey', {
-  enumerable: true,
-  get: function () {
-    return InteractionMetadataKey;
-  }
-});
-Object.defineProperty(exports, 'InteractionRouteKeys', {
-  enumerable: true,
-  get: function () {
-    return InteractionRouteKeys;
-  }
-});
-Object.defineProperty(exports, 'InteractionRoutes', {
-  enumerable: true,
-  get: function () {
-    return InteractionRoutes;
-  }
-});
-Object.defineProperty(exports, 'MiddlewareMetadataKey', {
-  enumerable: true,
-  get: function () {
-    return MiddlewareMetadataKey;
-  }
-});
 Object.defineProperty(exports, 'MissingPermissions', {
   enumerable: true,
   get: function () {
@@ -1217,28 +966,16 @@ Object.defineProperty(exports, 'RequireRole', {
     return RequireRole;
   }
 });
-Object.defineProperty(exports, 'RowComponent', {
-  enumerable: true,
-  get: function () {
-    return RowComponent;
-  }
-});
 Object.defineProperty(exports, 'SelectMenuKind', {
   enumerable: true,
   get: function () {
     return SelectMenuKind;
   }
 });
-Object.defineProperty(exports, 'SubscribeMetadataKey', {
-  enumerable: true,
-  get: function () {
-    return SubscribeMetadataKey;
-  }
-});
-Object.defineProperty(exports, 'WebhookUrlMetadataKey', {
+Object.defineProperty(exports, 'Silence', {
   enumerable: true,
   get: function () {
-    return WebhookUrlMetadataKey;
+    return Silence;
   }
 });
 Object.defineProperty(exports, 'areRoutes', {
@@ -1331,12 +1068,6 @@ Object.defineProperty(exports, 'selectMenuRouteOf', {
     return selectMenuRouteOf;
   }
 });
-Object.defineProperty(exports, 'setBotColor', {
-  enumerable: true,
-  get: function () {
-    return setBotColor;
-  }
-});
 Object.defineProperty(exports, 'storeComponentRoute', {
   enumerable: true,
   get: function () {
@@ -1349,4 +1080,4 @@ Object.defineProperty(exports, 'storeInteractionRoute', {
     return storeInteractionRoute;
   }
 });
-//# sourceMappingURL=permissions-DSW_EZfN.cjs.map
+//# sourceMappingURL=Silence-DiP95iwD.cjs.map