@seedcord/core 0.1.0-next.7 → 0.1.0

package/dist/{Plugin-3rlH0uxH.d.mts → Plugin-BZit5HUI.d.mts}

@@ -1,6 +1,7 @@
 import { FrameworkChannel, Logger } from "@seedcord/logger";
 import { TypedEventEmitter } from "@seedcord/event-emitter";
-import { Config, EventFrequency, HmrAware, HmrUpdateEvent, IRateLimiter, RenderContext, ReplyResponse, Store, Tail, TypedExclude } from "@seedcord/types";
+import { REST } from "@discordjs/rest";
+import { Config, EventFrequency, HmrAware, HmrUpdateEvent, IRateLimiter, RenderContext, ReplyResponse, Tail, TypedExclude } from "@seedcord/types";
 import { UUID } from "node:crypto";
 
 //#region src/metadataKeys.d.ts
@@ -384,116 +385,17 @@ declare class Bus extends TypedEventEmitter<SubscriptionTuples> {
 interface CoreBase {
   /** Transports narrow this to their own config type. */
   readonly config: Config;
+  /**
+   * Discord REST client. On gateway this is the discord.js client's own, and it carries no token
+   * until the Login phase. On http the token is set by `start()`.
+   */
+  readonly rest: REST;
   /** Sliding-window rate limiting, the `Cooldown` gate's backend and a public direct-use API. */
   readonly rateLimiter: IRateLimiter;
   /** Publish and subscribe to framework and application events. */
   readonly bus: Bus;
 }
 //#endregion
-//#region src/plugin/options.d.ts
-/** A capability a plugin declares through `needs`, each surfacing a typed `ctx` field. */
-type PluginNeed = 'client' | 'token' | 'rest';
-/**
- * The options a plugin declares as its `Plugin<Opts>` type argument. Authors write unions for `needs`,
- * e.g. `needs: 'token' | 'rest'`.
- */
-interface PluginOptions {
-  /**
-   * Which transport the plugin runs on. `'any'` attaches to either one.
-   * @defaultValue 'any'
-   */
-  transport?: 'gateway' | 'http' | 'any';
-  /**
-   * Which runtime the plugin runs on. `'any'` attaches to either one.
-   * @defaultValue 'any'
-   */
-  runtime?: 'server' | 'edge' | 'any';
-  /** Capabilities the plugin requests, each a typed `ctx` field. */
-  needs?: PluginNeed;
-}
-/** @internal */
-type TransportOf<Opts extends PluginOptions> = undefined extends Opts['transport'] ? 'any' : NonNullable<Opts['transport']>;
-/** @internal */
-type RuntimeOf<Opts extends PluginOptions> = undefined extends Opts['runtime'] ? 'any' : NonNullable<Opts['runtime']>;
-/** @internal */
-type NeedsOf<Opts extends PluginOptions> = undefined extends Opts['needs'] ? never : NonNullable<Opts['needs']>;
-/** @internal the transport a bot runs */
-type Transport = TypedExclude<NonNullable<PluginOptions['transport']>, 'any'>;
-/** @internal the runtime a bot runs */
-type Runtime = TypedExclude<NonNullable<PluginOptions['runtime']>, 'any'>;
-type TransportMismatch<PluginT extends string, BotT extends string> = Record<`this plugin declares transport '${PluginT}' but this bot runs '${BotT}'`, never>;
-type RuntimeMismatch<PluginRt extends string, BotRt extends string> = Record<`this plugin declares runtime '${PluginRt}' but this bot runs '${BotRt}'`, never>;
-type EdgePluginsUnsupported = Record<'an edge bot takes no plugins until edge support ships after v1', never>;
-/** @internal */
-type ChannelKeyAssert<Key extends string> = Key extends FrameworkChannel ? `'${Key}' is a channel the framework logs on. Pick another plugin key.` : Key;
-type BrandTransport<Plug> = Plug extends {
-  readonly __transport?: infer T extends string;
-} ? T : 'any';
-type BrandRuntime<Plug> = Plug extends {
-  readonly __runtime?: infer R extends string;
-} ? R : 'any';
-/** @internal */
-type TransportAssert<Plug, BotT extends Transport> = BrandTransport<Plug> extends 'any' | BotT ? unknown : TransportMismatch<BrandTransport<Plug>, BotT>;
-/** @internal */
-type RuntimeAssert<Plug, BotRt extends Runtime> = 'edge' extends BotRt ? EdgePluginsUnsupported : BrandRuntime<Plug> extends 'any' | BotRt ? unknown : RuntimeMismatch<BrandRuntime<Plug>, BotRt>;
-//#endregion
-//#region src/plugin/context.d.ts
-/**
- * The type each `ctx` capability resolves to. Empty in core, each transport augments it through
- * declaration merging.
- *
- * @example
- * ```typescript
- * declare module '@seedcord/core' {
- *   interface PluginCapabilityTypes {
- *     client: Client;
- *     rest: REST;
- *   }
- * }
- * ```
- */
-interface PluginCapabilityTypes {}
-type CapabilityType<Key extends PluginNeed, Fallback> = Key extends keyof PluginCapabilityTypes ? PluginCapabilityTypes[Key] : Fallback;
-type CapabilityValue<TNeeds extends PluginNeed, Key extends PluginNeed, Value> = Key extends TNeeds ? Value : never;
-/**
- * The framework surface a plugin reads through `this.ctx`, typed by its declared `needs`.
- *
- * Always available: `config` and `store`. Each capability resolves to its value only when
- * the plugin declared that key, otherwise `never`. The logger comes from `this.logger`.
- *
- * @typeParam TNeeds - The plugin's declared `needs` union.
- */
-interface PluginContext<TNeeds extends PluginNeed = never> {
-  readonly config: Config;
-  readonly store: Store<'charge'>;
-  readonly client: CapabilityValue<TNeeds, 'client', CapabilityType<'client', unknown>>;
-  readonly token: CapabilityValue<TNeeds, 'token', string>;
-  /**
-   * The REST client. On http, the client has no token until the Ready phase, so a call from
-   * `init()` sends without a token and returns a 401.
-   */
-  readonly rest: CapabilityValue<TNeeds, 'rest', CapabilityType<'rest', unknown>>;
-}
-/** @internal */
-type StoredPluginContext = Pick<PluginContext, 'config' | 'store'> & {
-  client?: unknown;
-  token?: string | undefined;
-  rest?: unknown;
-};
-/**
- * The capability arms a transport supplies from its own Bot/client. `attach` merges them into each
- * plugin's ctx.
- *
- * @internal
- */
-interface PluginCapabilities {
-  readonly client?: unknown;
-  readonly token?: string | undefined;
-  readonly rest?: unknown;
-}
-/** @internal unset until attach installs the built ctx */
-declare const pluginContextSlot: unique symbol;
-//#endregion
 //#region src/lifecycle/phases.d.ts
 /**
  * Startup phases, in run order.
@@ -501,7 +403,7 @@ declare const pluginContextSlot: unique symbol;
 declare enum StartupPhase {
   /** Nothing connected. Plugin init runs here by default. */
   Configuration = 1,
-  /** The gateway session opens. Empty on http. */
+  /** The gateway session opens, and http runs its REST-only startup work. */
   Login = 2,
   /** Handlers are live and interactions dispatch. */
   Ready = 3
@@ -553,6 +455,44 @@ interface ResolvedPluginLifecycleSpec {
   };
 }
 //#endregion
+//#region src/plugin/options.d.ts
+/** The options a plugin declares as its `Plugin<Opts>` type argument. */
+interface PluginOptions {
+  /**
+   * Which transport the plugin runs on. `'any'` attaches to either one.
+   * @defaultValue 'any'
+   */
+  transport?: 'gateway' | 'http' | 'any';
+  /**
+   * Which runtime the plugin runs on. `'any'` attaches to either one.
+   * @defaultValue 'any'
+   */
+  runtime?: 'server' | 'edge' | 'any';
+}
+/** @internal */
+type TransportOf<Opts extends PluginOptions> = undefined extends Opts['transport'] ? 'any' : NonNullable<Opts['transport']>;
+/** @internal */
+type RuntimeOf<Opts extends PluginOptions> = undefined extends Opts['runtime'] ? 'any' : NonNullable<Opts['runtime']>;
+/** @internal the transport a bot runs */
+type Transport = TypedExclude<NonNullable<PluginOptions['transport']>, 'any'>;
+/** @internal the runtime a bot runs */
+type Runtime = TypedExclude<NonNullable<PluginOptions['runtime']>, 'any'>;
+type TransportMismatch<PluginT extends string, BotT extends string> = Record<`this plugin declares transport '${PluginT}' but this bot runs '${BotT}'`, never>;
+type RuntimeMismatch<PluginRt extends string, BotRt extends string> = Record<`this plugin declares runtime '${PluginRt}' but this bot runs '${BotRt}'`, never>;
+type EdgePluginsUnsupported = Record<'an edge bot takes no plugins until edge support ships after v1', never>;
+/** @internal */
+type ChannelKeyAssert<Key extends string> = Key extends FrameworkChannel ? `'${Key}' is a channel the framework logs on. Pick another plugin key.` : Key;
+type BrandTransport<Plug> = Plug extends {
+  readonly __transport?: infer T extends string;
+} ? T : 'any';
+type BrandRuntime<Plug> = Plug extends {
+  readonly __runtime?: infer R extends string;
+} ? R : 'any';
+/** @internal */
+type TransportAssert<Plug, BotT extends Transport> = BrandTransport<Plug> extends 'any' | BotT ? unknown : TransportMismatch<BrandTransport<Plug>, BotT>;
+/** @internal */
+type RuntimeAssert<Plug, BotRt extends Runtime> = 'edge' extends BotRt ? EdgePluginsUnsupported : BrandRuntime<Plug> extends 'any' | BotRt ? unknown : RuntimeMismatch<BrandRuntime<Plug>, BotRt>;
+//#endregion
 //#region src/plugin/Plugin.d.ts
 interface Initializeable {
   init(): Promise<void>;
@@ -561,7 +501,7 @@ interface Initializeable {
 declare const resolvedSpecSlot: unique symbol;
 /**
  * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
- * implements `init()`, and reads the framework surface through `this.ctx`.
+ * implements `init()`, and reads the framework surface through `this.core`.
  *
  * @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`.
@@ -574,15 +514,11 @@ declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends Cor
   readonly __runtime?: RuntimeOf<Opts>;
   /** @internal */
   readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;
-  /** @internal */
-  [pluginContextSlot]?: StoredPluginContext;
-  /** Logs under the plugin's class name, on the channel its attach key names. */
+  /** Logs under the plugin's class name, on the channel its attach key sets. */
   readonly logger: Logger;
   constructor(host: CoreBase, spec?: PluginLifecycleSpec);
   /** The host, typed to the transport whose `Plugin` base this class extends. */
   protected get core(): TCore;
-  /** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
-  protected get ctx(): PluginContext<NeedsOf<Opts>>;
   abstract init(): Promise<void>;
   /**
    * Runs in the startup Ready phase, after `init()`. The gateway client is logged in by this phase,
@@ -592,8 +528,7 @@ declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends Cor
   /** Runs during teardown, only when `init()` resolved. */
   dispose?(): Promise<void>;
   /**
-   * Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
-   * plugin class and the reason.
+   * Throws a `SeedcordError` that contains the plugin class name and the reason.
    *
    * @param reason - Why the options are invalid.
    */
@@ -607,7 +542,7 @@ declare abstract class Plugin<Opts extends PluginOptions = {}, TCore extends Cor
   protected registerCriticalFiles(patterns: string[]): void;
 }
 /** @internal */
-type PluginLike = Pick<Plugin, 'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot | typeof pluginContextSlot>;
+type PluginLike = Pick<Plugin, 'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot>;
 /** @internal */
 type PluginCtor<TPlugin extends PluginLike = PluginLike> = new (...args: any[]) => TPlugin;
 /** @internal */
@@ -616,5 +551,5 @@ type CoreParamTooNarrow = Record<'this plugin constructor must take CoreBase as
 /** @internal */
 type CoreParamAssert<Ctor extends PluginCtor> = CoreBase extends ConstructorParameters<Ctor>[0] ? unknown : CoreParamTooNarrow;
 //#endregion
-export { Notice as A, EventMetadataKey as B, Subscriber as C, SubscriptionData as D, FaultSource as E, checkAckLegality as F, MiddlewareMetadataKey as G, InteractionMetadataKey as H, sendTarget as I, SubscribeMetadataKey as K, AckTrace as L, reportedWrite as M, AckState as N, SubscriptionKey as O, ReplyMethod as P, PublishDefault as R, SubscriberRegistration as S, DispatchOutcome as T, InteractionRouteKeys as U, GatedMetadataKey as V, InteractionRoutes as W, Transport as _, PluginCtor as a, Bus as b, ShutdownPhase as c, PluginCapabilityTypes as d, PluginContext as f, RuntimeAssert as g, Runtime as h, PluginArgs as i, ReplyTelemetry as j, Subscriptions as k, StartupPhase as l, PluginOptions as m, Initializeable as n, PluginLike as o, ChannelKeyAssert as p, WebhookUrlMetadataKey as q, Plugin as r, PluginLifecycleSpec as s, CoreParamAssert as t, PluginCapabilities as u, TransportAssert as v, DefaultSubscriptions as w, StoredSubscriberCtor as x, CoreBase as y, CommandMetadataKey as z };
-//# sourceMappingURL=Plugin-3rlH0uxH.d.mts.map
+export { AckState as A, InteractionRouteKeys as B, FaultSource as C, Notice as D, Subscriptions as E, PublishDefault as F, MiddlewareMetadataKey as H, CommandMetadataKey as I, EventMetadataKey as L, checkAckLegality as M, sendTarget as N, ReplyTelemetry as O, AckTrace as P, GatedMetadataKey as R, DispatchOutcome as S, SubscriptionKey as T, SubscribeMetadataKey as U, InteractionRoutes as V, WebhookUrlMetadataKey as W, Bus as _, PluginCtor as a, Subscriber as b, PluginOptions as c, Transport as d, TransportAssert as f, CoreBase as g, StartupPhase as h, PluginArgs as i, ReplyMethod as j, reportedWrite as k, Runtime as l, ShutdownPhase as m, Initializeable as n, PluginLike as o, PluginLifecycleSpec as p, Plugin as r, ChannelKeyAssert as s, CoreParamAssert as t, RuntimeAssert as u, StoredSubscriberCtor as v, SubscriptionData as w, DefaultSubscriptions as x, SubscriberRegistration as y, InteractionMetadataKey as z };
+//# sourceMappingURL=Plugin-BZit5HUI.d.mts.map

package/dist/{Plugin-Cgp1a0uQ.cjs → Plugin-BlkhHNRm.cjs}

@@ -1,24 +1,9 @@
-const require_phases = require('./phases-C_BGNyVo.cjs');
+const require_phases = require('./phases-DcuDHoQl.cjs');
 const require_devChannel = require('./devChannel-CoCmAVDx.cjs');
+let _seedcord_logger = require("@seedcord/logger");
 let _seedcord_errors = require("@seedcord/errors");
 let _seedcord_errors_internal = require("@seedcord/errors/internal");
-let _seedcord_logger = require("@seedcord/logger");
-
-//#region src/plugin/context.ts
-/** @internal unset until attach installs the built ctx */
-const pluginContextSlot = Symbol("seedcord.plugin.ctx");
-/** @internal */
-function readPluginContext(holder) {
-	const ctx = holder[pluginContextSlot];
-	if (!ctx) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);
-	return ctx;
-}
-/** @internal */
-function finalizePluginContext(holder, ctx) {
-	holder[pluginContextSlot] = ctx;
-}
 
-//#endregion
 //#region src/plugin/lifecycle.ts
 const DEFAULT_INIT_TIMEOUT_MS = 15e3;
 const DEFAULT_READY_TIMEOUT_MS = 15e3;
@@ -49,7 +34,7 @@ function resolveLifecycleSpec(spec, pluginName) {
 const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
 /**
 * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
-* implements `init()`, and reads the framework surface through `this.ctx`.
+* implements `init()`, and reads the framework surface through `this.core`.
 *
 * @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`.
@@ -58,9 +43,7 @@ var Plugin = class {
 	host;
 	/** @internal */
 	[resolvedSpecSlot];
-	/** @internal */
-	[pluginContextSlot];
-	/** Logs under the plugin's class name, on the channel its attach key names. */
+	/** Logs under the plugin's class name, on the channel its attach key sets. */
 	logger;
 	constructor(host, spec) {
 		this.host = host;
@@ -71,13 +54,8 @@ var Plugin = class {
 	get core() {
 		return this.host;
 	}
-	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
-	get ctx() {
-		return readPluginContext(this);
-	}
 	/**
-	* Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
-	* plugin class and the reason.
+	* Throws a `SeedcordError` that contains the plugin class name and the reason.
 	*
 	* @param reason - Why the options are invalid.
 	*/
@@ -108,16 +86,10 @@ Object.defineProperty(exports, 'Plugin', {
     return Plugin;
   }
 });
-Object.defineProperty(exports, 'finalizePluginContext', {
-  enumerable: true,
-  get: function () {
-    return finalizePluginContext;
-  }
-});
 Object.defineProperty(exports, 'resolvedLifecycleSpecOf', {
   enumerable: true,
   get: function () {
     return resolvedLifecycleSpecOf;
   }
 });
-//# sourceMappingURL=Plugin-Cgp1a0uQ.cjs.map
+//# sourceMappingURL=Plugin-BlkhHNRm.cjs.map

package/dist/Plugin-BlkhHNRm.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-BlkhHNRm.cjs","names":["SeedcordError","SeedcordErrorCode","Logger","SeedcordError","SeedcordErrorCode"],"sources":["../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["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 { resolveLifecycleSpec } from './lifecycle';\n\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, 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.core`.\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\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\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    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     * 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\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<Plugin, 'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot>;\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"],"mappings":";;;;;;;AAsBA,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,IAAIA,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;;;;;AC1CA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAcyB;;CAPrB,CAAU;;CAGV,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;;;;;;CAkBA,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-j9GYdroS.mjs → Plugin-CDAV7P9l.mjs}

@@ -1,24 +1,9 @@
-import { n as StartupPhase, t as ShutdownPhase } from "./phases-BfpAG6w3.mjs";
+import { n as StartupPhase, t as ShutdownPhase } from "./phases-BauKJOTT.mjs";
 import { t as getDevChannel } from "./devChannel-CQU7hq7Q.mjs";
+import { Logger } from "@seedcord/logger";
 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 */
-const pluginContextSlot = Symbol("seedcord.plugin.ctx");
-/** @internal */
-function readPluginContext(holder) {
-	const ctx = holder[pluginContextSlot];
-	if (!ctx) throw new SeedcordError(SeedcordErrorCode.PluginContextBeforeInit, [holder.constructor.name]);
-	return ctx;
-}
-/** @internal */
-function finalizePluginContext(holder, ctx) {
-	holder[pluginContextSlot] = ctx;
-}
 
-//#endregion
 //#region src/plugin/lifecycle.ts
 const DEFAULT_INIT_TIMEOUT_MS = 15e3;
 const DEFAULT_READY_TIMEOUT_MS = 15e3;
@@ -49,7 +34,7 @@ function resolveLifecycleSpec(spec, pluginName) {
 const resolvedSpecSlot = Symbol("seedcord.plugin.spec");
 /**
 * Base class for Seedcord plugins. A subclass declares its options as the `Opts` type argument,
-* implements `init()`, and reads the framework surface through `this.ctx`.
+* implements `init()`, and reads the framework surface through `this.core`.
 *
 * @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`.
@@ -58,9 +43,7 @@ var Plugin = class {
 	host;
 	/** @internal */
 	[resolvedSpecSlot];
-	/** @internal */
-	[pluginContextSlot];
-	/** Logs under the plugin's class name, on the channel its attach key names. */
+	/** Logs under the plugin's class name, on the channel its attach key sets. */
 	logger;
 	constructor(host, spec) {
 		this.host = host;
@@ -71,13 +54,8 @@ var Plugin = class {
 	get core() {
 		return this.host;
 	}
-	/** The framework surface, available from `init()` onward. Throws if read before `attach` finalizes it. */
-	get ctx() {
-		return readPluginContext(this);
-	}
 	/**
-	* Rejects the plugin's constructor options with a reason. Throws a `SeedcordError` naming the
-	* plugin class and the reason.
+	* Throws a `SeedcordError` that contains the plugin class name and the reason.
 	*
 	* @param reason - Why the options are invalid.
 	*/
@@ -102,5 +80,5 @@ function resolvedLifecycleSpecOf(plugin) {
 }
 
 //#endregion
-export { resolvedLifecycleSpecOf as n, finalizePluginContext as r, Plugin as t };
-//# sourceMappingURL=Plugin-j9GYdroS.mjs.map
+export { resolvedLifecycleSpecOf as n, Plugin as t };
+//# sourceMappingURL=Plugin-CDAV7P9l.mjs.map

package/dist/Plugin-CDAV7P9l.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-CDAV7P9l.mjs","names":[],"sources":["../src/plugin/lifecycle.ts","../src/plugin/Plugin.ts"],"sourcesContent":["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 { resolveLifecycleSpec } from './lifecycle';\n\nimport type { ResolvedPluginLifecycleSpec, PluginLifecycleSpec } from './lifecycle';\nimport type { TransportOf, 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.core`.\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\n    /** Logs under the plugin's class name, on the channel its attach key sets. */\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    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     * 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\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<Plugin, 'init' | 'ready' | 'dispose' | 'logger' | 'onHmr' | typeof resolvedSpecSlot>;\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"],"mappings":";;;;;;;AAsBA,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;;;;;AC1CA,MAAM,mBAAmB,OAAO,sBAAsB;;;;;;;;AAStD,IAAsB,SAAtB,MAEA;CAcyB;;CAPrB,CAAU;;CAGV,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;;;;;;CAkBA,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/basic-1hebYVcN.d.mts

@@ -0,0 +1,22 @@
+import { ContextMenuCommandBuilder, SlashCommandBuilder } from "@discordjs/builders";
+import { APIApplicationCommand } from "discord-api-types/v10";
+
+//#region src/commands/types.d.ts
+/** @internal */
+type CommandBuilder = SlashCommandBuilder | ContextMenuCommandBuilder;
+/** The commands Discord returns from each scope's deploy, keyed by command id. @internal */
+interface DeployResult {
+  global: Map<string, APIApplicationCommand>;
+  guilds: Map<string, Map<string, APIApplicationCommand>>;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.7.0/node_modules/type-fest/source/basic.d.ts
+/**
+Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+
+@category Class
+*/
+type Constructor<T, Arguments extends unknown[] = any[]> = new (...arguments_: Arguments) => T;
+//#endregion
+export { CommandBuilder as n, DeployResult as r, Constructor as t };
+//# sourceMappingURL=basic-1hebYVcN.d.mts.map

package/dist/contextMenuLeaves-f2rbyo83.d.mts

@@ -0,0 +1,19 @@
+import { ContextMenuCommandBuilder, SlashCommandBuilder } from "@discordjs/builders";
+
+//#region src/commands/contextMenuLeaves.d.ts
+/** The registered context-menu command names, split by kind. @internal */
+interface ContextMenuLeaves {
+  readonly user: Set<string>;
+  readonly message: Set<string>;
+}
+/**
+ * Collects the names of every registered context-menu command across a set of command builders, deduplicated
+ * because the same builder appears once per guild. A user and a message command can share a name, so the two
+ * kinds stay in separate sets.
+ *
+ * @internal
+ */
+declare function contextMenuLeaves(commands: Iterable<SlashCommandBuilder | ContextMenuCommandBuilder>): ContextMenuLeaves;
+//#endregion
+export { contextMenuLeaves as n, ContextMenuLeaves as t };
+//# sourceMappingURL=contextMenuLeaves-f2rbyo83.d.mts.map