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

package/dist/Plugin-C2-VHrsX.cjs

@@ -0,0 +1,114 @@
+const require_phases = require('./phases-C_BGNyVo.cjs');
+const require_devChannel = require('./devChannel-CoCmAVDx.cjs');
+let _seedcord_errors = require("@seedcord/errors");
+let _seedcord_errors_internal = require("@seedcord/errors/internal");
+
+//#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;
+const DEFAULT_DISPOSE_TIMEOUT_MS = 1e4;
+function timeoutOf(field, declared, fallback, pluginName) {
+	if (declared === void 0) return fallback;
+	if (!Number.isFinite(declared) || declared <= 0) throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginOptionsRejected, [pluginName, `lifecycle ${field}.timeout must be a positive number of milliseconds`]);
+	return declared;
+}
+/** @internal */
+function resolveLifecycleSpec(spec, pluginName) {
+	return {
+		init: {
+			phase: spec?.init?.phase ?? 1,
+			timeout: timeoutOf("init", spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)
+		},
+		ready: { timeout: timeoutOf("ready", spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName) },
+		dispose: {
+			phase: spec?.dispose?.phase ?? 3,
+			timeout: timeoutOf("dispose", spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)
+		}
+	};
+}
+
+//#endregion
+//#region src/plugin/Plugin.ts
+/** @internal */
+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`.
+*
+* @typeParam Opts - The plugin's declared {@link PluginOptions}.
+*/
+var Plugin = class {
+	pluggable;
+	/** @internal */
+	[resolvedSpecSlot];
+	/** @internal */
+	[pluginContextSlot];
+	constructor(pluggable, spec) {
+		this.pluggable = pluggable;
+		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
+	}
+	/** 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.
+	*
+	* @param reason - Why the options are invalid.
+	*/
+	rejectOptions(reason) {
+		throw new _seedcord_errors_internal.SeedcordError(_seedcord_errors.SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);
+	}
+	/** Override to reload plugin state on an HMR update. */
+	onHmr(_event) {
+		return Promise.resolve();
+	}
+	/**
+	* Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+	* @param patterns - Glob patterns relative to the project root
+	*/
+	registerCriticalFiles(patterns) {
+		require_devChannel.getDevChannel()?.send("seedcord:register-critical-files", { patterns });
+	}
+};
+/** @internal */
+function resolvedLifecycleSpecOf(plugin) {
+	return plugin[resolvedSpecSlot];
+}
+
+//#endregion
+Object.defineProperty(exports, 'Plugin', {
+  enumerable: true,
+  get: function () {
+    return Plugin;
+  }
+});
+Object.defineProperty(exports, 'finalizePluginContext', {
+  enumerable: true,
+  get: function () {
+    return finalizePluginContext;
+  }
+});
+Object.defineProperty(exports, 'resolvedLifecycleSpecOf', {
+  enumerable: true,
+  get: function () {
+    return resolvedLifecycleSpecOf;
+  }
+});
+//# sourceMappingURL=Plugin-C2-VHrsX.cjs.map

package/dist/Plugin-C2-VHrsX.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-C2-VHrsX.cjs","names":["SeedcordError","SeedcordErrorCode","SeedcordError","SeedcordErrorCode","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 { Logger } from '@seedcord/logger';\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: `logger`, `config`, `store`. Each capability resolves to its value only when\n * the plugin declared that key, otherwise `never`.\n *\n * @typeParam TNeeds - The plugin's declared `needs` union.\n */\nexport interface PluginContext<TNeeds extends PluginNeed = never> {\n    readonly logger: Logger;\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, 'logger' | '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';\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 { Logger } from '@seedcord/logger';\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 */\nexport abstract class Plugin<Opts extends PluginOptions = {}> implements Initializeable, HmrAware {\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    public abstract logger: Logger;\n\n    // subclasses redeclare the transport's own Core type on their constructor\n    constructor(\n        protected pluggable: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\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: Plugin): 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/**\n * Constructor type for plugins that can accept extra arguments after Core.\n *\n * The first parameter stays untyped here. Subclasses declare their transport's own `Core`, and a\n * `CoreBase` parameter would reject them (construct-signature params check contravariantly). The\n * `Plugin` base constructor carries the real contract, and attach call sites still infer the\n * concrete subclass tuple for the trailing args.\n *\n * @internal\n */\nexport type PluginCtor<TPlugin extends Plugin = Plugin> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\nexport { finalizePluginContext } from './context';\n"],"mappings":";;;;;;;AAuEA,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;;;;ACrEA,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;;;;;;;AAQtD,IAAsB,SAAtB,MAAkG;CAehF;;CARd,CAAU;;CAEV,CAAC;CAKD,YACI,AAAU,WACV,MACF;EAFY;EAGV,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;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,QAA6C;CACjF,OAAO,OAAO;AAClB"}

package/dist/Plugin-CNyRKDHT.d.mts

@@ -0,0 +1,226 @@
+import { Logger } from "@seedcord/logger";
+import { Config, HmrAware, HmrUpdateEvent, IRateLimiter, Store, Tail } from "@seedcord/types";
+
+//#region src/interfaces/CoreBase.d.ts
+/**
+ * The transport-agnostic slice of the running framework, what core code (gates, notices, plugins'
+ * agnostic surface) accesses through `ctx.core`. Each transport's `Core` extends it, the gateway
+ * adds `bot` and `bus`.
+ */
+interface CoreBase {
+  /** Transports narrow this to their own config type. */
+  readonly config: Config;
+  /** Sliding-window rate limiting, the `Cooldown` gate's backend and a public direct-use API. */
+  readonly rateLimiter: IRateLimiter;
+}
+//#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.
+   * @defaultValue 'both'
+   */
+  transport?: 'gateway' | 'http' | 'both';
+  /**
+   * Which runtime the plugin runs on.
+   * @defaultValue 'both'
+   */
+  runtime?: 'server' | 'edge' | 'both';
+  /** Capabilities the plugin requests, each a typed `ctx` field. */
+  needs?: PluginNeed;
+}
+/** @internal */
+type TransportOf<Opts extends PluginOptions> = undefined extends Opts['transport'] ? 'both' : NonNullable<Opts['transport']>;
+/** @internal */
+type RuntimeOf<Opts extends PluginOptions> = undefined extends Opts['runtime'] ? 'both' : NonNullable<Opts['runtime']>;
+/** @internal */
+type NeedsOf<Opts extends PluginOptions> = undefined extends Opts['needs'] ? never : NonNullable<Opts['needs']>;
+//#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: `logger`, `config`, `store`. Each capability resolves to its value only when
+ * the plugin declared that key, otherwise `never`.
+ *
+ * @typeParam TNeeds - The plugin's declared `needs` union.
+ */
+interface PluginContext<TNeeds extends PluginNeed = never> {
+  readonly logger: Logger;
+  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, 'logger' | '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.
+ */
+declare enum StartupPhase {
+  /** Nothing connected. Plugin init runs here by default. */
+  Configuration = 1,
+  /** The gateway session opens. Empty on http. */
+  Login = 2,
+  /** Handlers are live and interactions dispatch. */
+  Ready = 3
+}
+/**
+ * Shutdown phases, in run order.
+ */
+declare enum ShutdownPhase {
+  /** Stop taking new interactions and requests. */
+  Unbind = 1,
+  /** Waits for in-flight work to settle and stops internal services. */
+  Drain = 2,
+  /** External resources close. Plugin dispose runs here by default. */
+  Disconnect = 3,
+  /** The client disconnects last so in-flight handlers can still reference it during drain. */
+  Logout = 4
+}
+//#endregion
+//#region src/plugin/lifecycle.d.ts
+/**
+ * The lifecycle a plugin declares through `super(host, spec)`. Unset fields resolve to the base
+ * defaults. `ready` runs at a fixed `StartupPhase.Ready`, so it takes only a timeout.
+ */
+interface PluginLifecycleSpec {
+  init?: {
+    phase?: StartupPhase;
+    timeout?: number;
+  };
+  ready?: {
+    timeout?: number;
+  };
+  dispose?: {
+    phase?: ShutdownPhase;
+    timeout?: number;
+  };
+}
+/** @internal */
+interface ResolvedPluginLifecycleSpec {
+  readonly init: {
+    readonly phase: StartupPhase;
+    readonly timeout: number;
+  };
+  readonly ready: {
+    readonly timeout: number;
+  };
+  readonly dispose: {
+    readonly phase: ShutdownPhase;
+    readonly timeout: number;
+  };
+}
+//#endregion
+//#region src/plugin/Plugin.d.ts
+interface Initializeable {
+  init(): Promise<void>;
+}
+/** @internal */
+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`.
+ *
+ * @typeParam Opts - The plugin's declared {@link PluginOptions}.
+ */
+declare abstract class Plugin<Opts extends PluginOptions = {}> implements Initializeable, HmrAware {
+  protected pluggable: CoreBase;
+  /** @internal phantom, never set at runtime */
+  readonly __transport?: TransportOf<Opts>;
+  /** @internal phantom, never set at runtime */
+  readonly __runtime?: RuntimeOf<Opts>;
+  /** @internal */
+  readonly [resolvedSpecSlot]: ResolvedPluginLifecycleSpec;
+  /** @internal */
+  [pluginContextSlot]?: StoredPluginContext;
+  abstract logger: Logger;
+  constructor(pluggable: CoreBase, spec?: PluginLifecycleSpec);
+  /** 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,
+   * and the http host runs its server-bind and health tasks in the same phase.
+   */
+  ready?(): Promise<void>;
+  /** 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.
+   *
+   * @param reason - Why the options are invalid.
+   */
+  protected rejectOptions(reason: string): never;
+  /** Override to reload plugin state on an HMR update. */
+  onHmr(_event: HmrUpdateEvent): Promise<void>;
+  /**
+   * Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+   * @param patterns - Glob patterns relative to the project root
+   */
+  protected registerCriticalFiles(patterns: string[]): void;
+}
+/**
+ * Constructor type for plugins that can accept extra arguments after Core.
+ *
+ * The first parameter stays untyped here. Subclasses declare their transport's own `Core`, and a
+ * `CoreBase` parameter would reject them (construct-signature params check contravariantly). The
+ * `Plugin` base constructor carries the real contract, and attach call sites still infer the
+ * concrete subclass tuple for the trailing args.
+ *
+ * @internal
+ */
+type PluginCtor<TPlugin extends Plugin = Plugin> = new (...args: any[]) => TPlugin;
+/** @internal */
+type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;
+//#endregion
+export { PluginLifecycleSpec as a, PluginCapabilities as c, PluginOptions as d, CoreBase as f, PluginCtor as i, PluginCapabilityTypes as l, Plugin as n, ShutdownPhase as o, PluginArgs as r, StartupPhase as s, Initializeable as t, PluginContext as u };
+//# sourceMappingURL=Plugin-CNyRKDHT.d.mts.map

package/dist/Plugin-PcdPjAzc.mjs

@@ -0,0 +1,97 @@
+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";
+
+//#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;
+const DEFAULT_DISPOSE_TIMEOUT_MS = 1e4;
+function timeoutOf(field, declared, fallback, pluginName) {
+	if (declared === void 0) return fallback;
+	if (!Number.isFinite(declared) || declared <= 0) throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [pluginName, `lifecycle ${field}.timeout must be a positive number of milliseconds`]);
+	return declared;
+}
+/** @internal */
+function resolveLifecycleSpec(spec, pluginName) {
+	return {
+		init: {
+			phase: spec?.init?.phase ?? 1,
+			timeout: timeoutOf("init", spec?.init?.timeout, DEFAULT_INIT_TIMEOUT_MS, pluginName)
+		},
+		ready: { timeout: timeoutOf("ready", spec?.ready?.timeout, DEFAULT_READY_TIMEOUT_MS, pluginName) },
+		dispose: {
+			phase: spec?.dispose?.phase ?? 3,
+			timeout: timeoutOf("dispose", spec?.dispose?.timeout, DEFAULT_DISPOSE_TIMEOUT_MS, pluginName)
+		}
+	};
+}
+
+//#endregion
+//#region src/plugin/Plugin.ts
+/** @internal */
+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`.
+*
+* @typeParam Opts - The plugin's declared {@link PluginOptions}.
+*/
+var Plugin = class {
+	pluggable;
+	/** @internal */
+	[resolvedSpecSlot];
+	/** @internal */
+	[pluginContextSlot];
+	constructor(pluggable, spec) {
+		this.pluggable = pluggable;
+		this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);
+	}
+	/** 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.
+	*
+	* @param reason - Why the options are invalid.
+	*/
+	rejectOptions(reason) {
+		throw new SeedcordError(SeedcordErrorCode.PluginOptionsRejected, [this.constructor.name, reason]);
+	}
+	/** Override to reload plugin state on an HMR update. */
+	onHmr(_event) {
+		return Promise.resolve();
+	}
+	/**
+	* Registers critical file patterns that should trigger a full restart when changed in Dev HMR.
+	* @param patterns - Glob patterns relative to the project root
+	*/
+	registerCriticalFiles(patterns) {
+		getDevChannel()?.send("seedcord:register-critical-files", { patterns });
+	}
+};
+/** @internal */
+function resolvedLifecycleSpecOf(plugin) {
+	return plugin[resolvedSpecSlot];
+}
+
+//#endregion
+export { resolvedLifecycleSpecOf as n, finalizePluginContext as r, Plugin as t };
+//# sourceMappingURL=Plugin-PcdPjAzc.mjs.map

package/dist/Plugin-PcdPjAzc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Plugin-PcdPjAzc.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 { Logger } from '@seedcord/logger';\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: `logger`, `config`, `store`. Each capability resolves to its value only when\n * the plugin declared that key, otherwise `never`.\n *\n * @typeParam TNeeds - The plugin's declared `needs` union.\n */\nexport interface PluginContext<TNeeds extends PluginNeed = never> {\n    readonly logger: Logger;\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, 'logger' | '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';\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 { Logger } from '@seedcord/logger';\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 */\nexport abstract class Plugin<Opts extends PluginOptions = {}> implements Initializeable, HmrAware {\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    public abstract logger: Logger;\n\n    // subclasses redeclare the transport's own Core type on their constructor\n    constructor(\n        protected pluggable: CoreBase,\n        spec?: PluginLifecycleSpec\n    ) {\n        this[resolvedSpecSlot] = resolveLifecycleSpec(spec, this.constructor.name);\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: Plugin): 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/**\n * Constructor type for plugins that can accept extra arguments after Core.\n *\n * The first parameter stays untyped here. Subclasses declare their transport's own `Core`, and a\n * `CoreBase` parameter would reject them (construct-signature params check contravariantly). The\n * `Plugin` base constructor carries the real contract, and attach call sites still infer the\n * concrete subclass tuple for the trailing args.\n *\n * @internal\n */\nexport type PluginCtor<TPlugin extends Plugin = Plugin> = new (...args: any[]) => TPlugin;\n\n/** @internal */\nexport type PluginArgs<Ctor extends PluginCtor> = Tail<ConstructorParameters<Ctor>>;\n\nexport { finalizePluginContext } from './context';\n"],"mappings":";;;;;;;AAuEA,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;;;;ACrEA,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;;;;;;;AAQtD,IAAsB,SAAtB,MAAkG;CAehF;;CARd,CAAU;;CAEV,CAAC;CAKD,YACI,AAAU,WACV,MACF;EAFY;EAGV,KAAK,oBAAoB,qBAAqB,MAAM,KAAK,YAAY,IAAI;CAC7E;;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,QAA6C;CACjF,OAAO,OAAO;AAClB"}

package/dist/devChannel-CQU7hq7Q.mjs

@@ -0,0 +1,14 @@
+//#region src/hmr/devChannel.ts
+let channel;
+/** @internal */
+function setDevChannel(next) {
+	channel = next;
+}
+/** @internal */
+function getDevChannel() {
+	return channel;
+}
+
+//#endregion
+export { setDevChannel as n, getDevChannel as t };
+//# sourceMappingURL=devChannel-CQU7hq7Q.mjs.map

package/dist/devChannel-CQU7hq7Q.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devChannel-CQU7hq7Q.mjs","names":[],"sources":["../src/hmr/devChannel.ts"],"sourcesContent":["import type { DevChannel, SeedcordCliEvents, SeedcordFrameworkEvents } from '@seedcord/types/internal';\n\n// one module instance per process, the HmrManager write and every framework read share it\nlet channel: DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents> | undefined;\n\n/** @internal */\nexport function setDevChannel(next: DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents> | undefined): void {\n    channel = next;\n}\n\n/** @internal */\nexport function getDevChannel(): DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents> | undefined {\n    return channel;\n}\n"],"mappings":";AAGA,IAAI;;AAGJ,SAAgB,cAAc,MAAgF;CAC1G,UAAU;AACd;;AAGA,SAAgB,gBAAoF;CAChG,OAAO;AACX"}

package/dist/devChannel-CoCmAVDx.cjs

@@ -0,0 +1,26 @@
+
+//#region src/hmr/devChannel.ts
+let channel;
+/** @internal */
+function setDevChannel(next) {
+	channel = next;
+}
+/** @internal */
+function getDevChannel() {
+	return channel;
+}
+
+//#endregion
+Object.defineProperty(exports, 'getDevChannel', {
+  enumerable: true,
+  get: function () {
+    return getDevChannel;
+  }
+});
+Object.defineProperty(exports, 'setDevChannel', {
+  enumerable: true,
+  get: function () {
+    return setDevChannel;
+  }
+});
+//# sourceMappingURL=devChannel-CoCmAVDx.cjs.map

package/dist/devChannel-CoCmAVDx.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"devChannel-CoCmAVDx.cjs","names":[],"sources":["../src/hmr/devChannel.ts"],"sourcesContent":["import type { DevChannel, SeedcordCliEvents, SeedcordFrameworkEvents } from '@seedcord/types/internal';\n\n// one module instance per process, the HmrManager write and every framework read share it\nlet channel: DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents> | undefined;\n\n/** @internal */\nexport function setDevChannel(next: DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents> | undefined): void {\n    channel = next;\n}\n\n/** @internal */\nexport function getDevChannel(): DevChannel<SeedcordFrameworkEvents, SeedcordCliEvents> | undefined {\n    return channel;\n}\n"],"mappings":";;AAGA,IAAI;;AAGJ,SAAgB,cAAc,MAAgF;CAC1G,UAAU;AACd;;AAGA,SAAgB,gBAAoF;CAChG,OAAO;AACX"}