spearkit 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1,11 +1,524 @@
 'use strict';
 
 var discord_js = require('discord.js');
+var fs = require('fs');
+var util = require('util');
 var promises = require('fs/promises');
 var path = require('path');
 var url = require('url');
 
 // src/index.ts
+var DEFAULT_EMBED_COLORS = {
+  error: 15747655,
+  success: 4437378,
+  info: 3447003,
+  warn: 16361509
+};
+var DEFAULT_EMBED_ICONS = {
+  error: "\u26D4",
+  success: "\u2705",
+  info: "\u2139\uFE0F",
+  warn: "\u26A0\uFE0F"
+};
+var Embeds = class {
+  /** The resolved colors for every preset. */
+  colors;
+  /** The resolved icons for every preset. */
+  icons;
+  constructor(options = {}) {
+    this.colors = { ...DEFAULT_EMBED_COLORS, ...options.colors };
+    this.icons = { ...DEFAULT_EMBED_ICONS, ...options.icons };
+  }
+  /** Red preset — something went wrong. */
+  error(input) {
+    return this.build("error", input);
+  }
+  /** Green preset — something succeeded. */
+  success(input) {
+    return this.build("success", input);
+  }
+  /** Blue preset — neutral information. */
+  info(input) {
+    return this.build("info", input);
+  }
+  /** Yellow preset — caution. */
+  warn(input) {
+    return this.build("warn", input);
+  }
+  /** Build an embed at a chosen level. */
+  build(level, input) {
+    const builder = new discord_js.EmbedBuilder().setColor(this.colors[level]);
+    const icon = this.icons[level];
+    const prefix = icon.length > 0 ? `${icon} ` : "";
+    if (typeof input === "string") {
+      builder.setDescription(`${prefix}${input}`);
+      return builder;
+    }
+    if (input.title !== void 0) builder.setTitle(input.title);
+    if (input.description !== void 0) {
+      builder.setDescription(`${prefix}${input.description}`);
+    }
+    if (input.fields !== void 0) builder.addFields(...input.fields);
+    if (input.footer !== void 0) builder.setFooter(input.footer);
+    if (input.author !== void 0) builder.setAuthor(input.author);
+    if (input.url !== void 0) builder.setURL(input.url);
+    if (input.timestamp !== void 0) {
+      builder.setTimestamp(
+        input.timestamp instanceof Date ? input.timestamp : new Date(input.timestamp)
+      );
+    }
+    if (input.thumbnail !== void 0) builder.setThumbnail(input.thumbnail.url);
+    if (input.image !== void 0) builder.setImage(input.image.url);
+    return builder;
+  }
+};
+var defaultEmbeds = new Embeds();
+
+// src/lock.ts
+var KeyedLock = class {
+  entries = /* @__PURE__ */ new Map();
+  defaultTtl;
+  sweepTimer;
+  constructor(options = {}) {
+    this.defaultTtl = options.ttl ?? 6e4;
+    const sweep = options.sweep ?? 15e3;
+    if (sweep > 0) {
+      this.sweepTimer = setInterval(() => this.sweep(), sweep);
+      if (typeof this.sweepTimer.unref === "function") this.sweepTimer.unref();
+    }
+  }
+  /** Try to acquire `key`. Returns a release function, or `null` if already held. */
+  tryAcquire(key, ttl = this.defaultTtl) {
+    const existing = this.entries.get(key);
+    if (existing !== void 0 && Date.now() - existing.createdAt < existing.ttl) {
+      return null;
+    }
+    this.entries.set(key, { createdAt: Date.now(), ttl });
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.entries.delete(key);
+    };
+  }
+  /** Whether `key` is currently held and not expired. */
+  isHeld(key) {
+    const entry = this.entries.get(key);
+    return entry !== void 0 && Date.now() - entry.createdAt < entry.ttl;
+  }
+  /**
+   * Run `fn` while holding `key`. If the key is already held, calls `onBusy`
+   * (or returns `undefined`) without ever calling `fn`. Always releases on
+   * return or throw.
+   */
+  async run(key, fn, options = {}) {
+    const release = this.tryAcquire(key, options.ttl ?? this.defaultTtl);
+    if (release === null) {
+      return options.onBusy !== void 0 ? await options.onBusy() : void 0;
+    }
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  }
+  /** Number of currently-tracked leases (including expired-but-unswept). */
+  get size() {
+    return this.entries.size;
+  }
+  /** Drop all known leases and stop the sweep timer. */
+  dispose() {
+    this.entries.clear();
+    if (this.sweepTimer !== void 0) clearInterval(this.sweepTimer);
+  }
+  /** Manually remove a single key without running anything. */
+  forget(key) {
+    return this.entries.delete(key);
+  }
+  sweep() {
+    const now = Date.now();
+    for (const [key, entry] of this.entries.entries()) {
+      if (now - entry.createdAt > entry.ttl) this.entries.delete(key);
+    }
+  }
+};
+
+// src/safe-fetch.ts
+var DEFAULT_TIMEOUT_MS = 5e3;
+async function withTimeout(promise, ms) {
+  let timer;
+  try {
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), ms);
+    });
+    return await Promise.race([promise.catch(() => null), timeout]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
+}
+async function fetchMember(guild, userId, options = {}) {
+  if (guild == null || userId == null || userId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = guild.members.cache.get(userId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    guild.members.fetch({ user: userId, force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchChannel(client, channelId, options = {}) {
+  if (client == null || channelId == null || channelId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = client.channels.cache.get(channelId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    client.channels.fetch(channelId, { force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchMessage(messages, messageId, options = {}) {
+  if (messages == null || messageId == null || messageId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = messages.cache.get(messageId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    messages.fetch({ message: messageId, force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchUser(client, userId, options = {}) {
+  if (client == null || userId == null || userId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = client.users.cache.get(userId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    client.users.fetch(userId, { force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchGuild(client, guildId, options = {}) {
+  if (client == null || guildId == null || guildId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = client.guilds.cache.get(guildId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    client.guilds.fetch({ guild: guildId, force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function fetchRole(guild, roleId, options = {}) {
+  if (guild == null || roleId == null || roleId.length === 0) return null;
+  if (options.cache !== false && options.force !== true) {
+    const cached = guild.roles.cache.get(roleId);
+    if (cached !== void 0) return cached;
+  }
+  return withTimeout(
+    guild.roles.fetch(roleId, { force: options.force ?? false }),
+    options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  );
+}
+async function safeTry(op) {
+  try {
+    return await op();
+  } catch {
+    return null;
+  }
+}
+async function withSafeTimeout(promise, timeoutMs) {
+  return withTimeout(promise, timeoutMs);
+}
+var safeFetch = {
+  member: fetchMember,
+  channel: fetchChannel,
+  message: fetchMessage,
+  user: fetchUser,
+  guild: fetchGuild,
+  role: fetchRole,
+  try: safeTry
+};
+
+// src/format.ts
+var EN = {
+  week: ["week", "weeks"],
+  day: ["day", "days"],
+  hour: ["hour", "hours"],
+  minute: ["minute", "minutes"],
+  second: ["second", "seconds"],
+  separator: " ",
+  zero: "0 seconds"
+};
+var TR = {
+  week: ["hafta", "hafta"],
+  day: ["g\xFCn", "g\xFCn"],
+  hour: ["saat", "saat"],
+  minute: ["dakika", "dakika"],
+  second: ["saniye", "saniye"],
+  separator: " ",
+  zero: "0 saniye"
+};
+var LABELS = {
+  en: EN,
+  "en-US": EN,
+  "en-GB": EN,
+  tr: TR,
+  "tr-TR": TR
+};
+var UNIT_MS = {
+  week: 7 * 864e5,
+  day: 864e5,
+  hour: 36e5,
+  minute: 6e4,
+  second: 1e3
+};
+var UNIT_ORDER = ["week", "day", "hour", "minute", "second"];
+function resolveLabels(locale) {
+  if (typeof locale === "object" && locale !== null) return locale;
+  if (locale === void 0) return EN;
+  return LABELS[locale] ?? LABELS[locale.split("-")[0] ?? ""] ?? EN;
+}
+function formatDuration(ms, options = {}) {
+  const labels = resolveLabels(options.locale);
+  if (!Number.isFinite(ms) || ms <= 0) return labels.zero;
+  const limit = options.largest ?? 2;
+  const units = options.units ?? UNIT_ORDER;
+  const parts = [];
+  let remaining = Math.floor(ms);
+  for (const unit of units) {
+    if (parts.length >= limit) break;
+    const size = UNIT_MS[unit];
+    if (remaining < size) continue;
+    const value = Math.floor(remaining / size);
+    remaining -= value * size;
+    const word = value === 1 ? labels[unit][0] : labels[unit][1];
+    parts.push(`${value} ${word}`);
+  }
+  return parts.length > 0 ? parts.join(labels.separator) : labels.zero;
+}
+var DURATION_PATTERN = /(\d+(?:\.\d+)?)\s*(milliseconds|millisecond|seconds|minutes|saniye|dakika|minute|second|weeks|hours|hafta|saat|week|hour|days|day|gün|gun|min|sec|ms|wk|hr|dk|m|s|h|d|w)/gi;
+var SHORT_TO_MS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+  s: 1e3,
+  sec: 1e3,
+  second: 1e3,
+  seconds: 1e3,
+  saniye: 1e3,
+  m: 6e4,
+  min: 6e4,
+  minute: 6e4,
+  minutes: 6e4,
+  dakika: 6e4,
+  dk: 6e4,
+  h: 36e5,
+  hr: 36e5,
+  hour: 36e5,
+  hours: 36e5,
+  saat: 36e5,
+  d: 864e5,
+  day: 864e5,
+  days: 864e5,
+  g\u00FCn: 864e5,
+  gun: 864e5,
+  w: 6048e5,
+  wk: 6048e5,
+  week: 6048e5,
+  weeks: 6048e5,
+  hafta: 6048e5
+};
+function parseDuration(input) {
+  const trimmed = input.trim().toLowerCase();
+  if (trimmed.length === 0) return null;
+  DURATION_PATTERN.lastIndex = 0;
+  let total = 0;
+  let matched = false;
+  for (; ; ) {
+    const match = DURATION_PATTERN.exec(trimmed);
+    if (match === null) break;
+    matched = true;
+    const value = Number(match[1]);
+    const unit = match[2] ?? "";
+    const ms = SHORT_TO_MS[unit];
+    if (ms !== void 0 && Number.isFinite(value)) total += value * ms;
+  }
+  return matched ? total : null;
+}
+function toEpochSeconds(date) {
+  return Math.floor((date instanceof Date ? date.getTime() : date) / 1e3);
+}
+function discordTimestamp(date, style = "f") {
+  return `<t:${toEpochSeconds(date)}:${style}>`;
+}
+function relativeTimestamp(date) {
+  return discordTimestamp(date, "R");
+}
+
+// src/cache.ts
+var MemoryCache = class {
+  store = /* @__PURE__ */ new Map();
+  /** Total number of stored (possibly expired) entries — primarily for tests. */
+  get size() {
+    return this.store.size;
+  }
+  async get(key) {
+    const entry = this.store.get(key);
+    if (entry === void 0) return void 0;
+    if (entry.expiresAt !== void 0 && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, options) {
+    const ttl = options?.ttl;
+    this.store.set(key, {
+      value,
+      expiresAt: ttl !== void 0 && ttl > 0 ? Date.now() + ttl : void 0
+    });
+  }
+  async delete(key) {
+    return this.store.delete(key);
+  }
+  async has(key) {
+    return await this.get(key) !== void 0;
+  }
+  async increment(key, delta = 1, options) {
+    const current = await this.get(key) ?? 0;
+    const next = current + delta;
+    const existing = this.store.get(key);
+    const ttl = options?.ttl;
+    if (ttl !== void 0 && ttl > 0) {
+      await this.set(key, next, { ttl });
+    } else if (existing?.expiresAt !== void 0) {
+      this.store.set(key, { value: next, expiresAt: existing.expiresAt });
+    } else {
+      await this.set(key, next);
+    }
+    return next;
+  }
+  async rateLimit(key, options) {
+    const now = Date.now();
+    const bucketKey = `__rl__:${key}`;
+    const entry = this.store.get(bucketKey);
+    const expired = entry === void 0 || entry.expiresAt === void 0 || entry.expiresAt <= now;
+    if (expired) {
+      const resetAt2 = now + options.windowMs;
+      this.store.set(bucketKey, { value: 1, expiresAt: resetAt2 });
+      return { allowed: true, remaining: Math.max(0, options.limit - 1), resetAt: resetAt2 };
+    }
+    const count = entry.value;
+    const resetAt = entry.expiresAt ?? now;
+    if (count >= options.limit) {
+      return { allowed: false, remaining: 0, resetAt };
+    }
+    this.store.set(bucketKey, { value: count + 1, expiresAt: resetAt });
+    return { allowed: true, remaining: Math.max(0, options.limit - count - 1), resetAt };
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+function createCache() {
+  return new MemoryCache();
+}
+var readFileAsync = util.promisify(fs.readFile);
+function loadConfig(options) {
+  const text = fs.readFileSync(options.file, options.encoding ?? "utf8");
+  const parser = options.parser ?? JSON.parse;
+  const parsed = parser(text);
+  return options.schema !== void 0 ? options.schema(parsed) : parsed;
+}
+async function loadConfigAsync(options) {
+  const text = await readFileAsync(options.file, options.encoding ?? "utf8");
+  const parser = options.parser ?? JSON.parse;
+  const parsed = parser(text);
+  return options.schema !== void 0 ? options.schema(parsed) : parsed;
+}
+function lookup(table, resourceName = "key") {
+  return (key) => {
+    const value = table[key];
+    if (value === void 0) {
+      throw new Error(`spearkit: ${resourceName} "${String(key)}" not found in config`);
+    }
+    return value;
+  };
+}
+function lookupOptional(table) {
+  return (key) => table[key];
+}
+function denied(reason) {
+  return { allowed: false, reason };
+}
+async function runGuards(ctx, guards) {
+  if (guards === void 0 || guards.length === 0) return { allowed: true };
+  for (const guard2 of guards) {
+    const result = await guard2(ctx);
+    if (result === true) continue;
+    if (result === false) return { allowed: false, reason: void 0 };
+    if (result.allowed === false) return { allowed: false, reason: result.reason };
+  }
+  return { allowed: true };
+}
+function guildOnly(reason = "This can only be used in a server.") {
+  return (ctx) => ctx.guildId !== null ? true : denied(reason);
+}
+function dmOnly(reason = "This can only be used in DMs.") {
+  return (ctx) => ctx.guildId === null ? true : denied(reason);
+}
+function memberRoleIds(member) {
+  if (member === null) return [];
+  const roles = member.roles;
+  if (Array.isArray(roles)) return roles;
+  return [...roles.cache.keys()];
+}
+function memberPermissionsBitField(member) {
+  if (member === null) return null;
+  const perms = member.permissions;
+  if (perms instanceof discord_js.PermissionsBitField) return perms;
+  if (typeof perms === "string") return new discord_js.PermissionsBitField(BigInt(perms));
+  return null;
+}
+function requireAnyRole(roleIds, reason = "You don't have permission to use this.") {
+  const set = new Set(roleIds);
+  return (ctx) => {
+    const ids = memberRoleIds(ctx.member);
+    return ids.some((id) => set.has(id)) ? true : denied(reason);
+  };
+}
+function requireAllRoles(roleIds, reason = "You're missing one of the required roles.") {
+  return (ctx) => {
+    const ids = new Set(memberRoleIds(ctx.member));
+    return roleIds.every((id) => ids.has(id)) ? true : denied(reason);
+  };
+}
+function requireOwner(ownerIds, reason = "This is owner-only.") {
+  const set = new Set(ownerIds);
+  return (ctx) => set.has(ctx.user.id) ? true : denied(reason);
+}
+function requireUserPermissions(permission, reason = "You don't have permission to use this.") {
+  return (ctx) => {
+    const bits = memberPermissionsBitField(ctx.member);
+    if (bits === null) return denied(reason);
+    return bits.has(permission) ? true : denied(reason);
+  };
+}
+function requireBotPermissions(permission, reason = "I don't have permission to do that here.") {
+  return async (ctx) => {
+    const guild = ctx.guild;
+    if (guild === null) return denied(reason);
+    const me = guild.members.me ?? await guild.members.fetchMe().catch(() => null);
+    if (me === null) return denied(reason);
+    return me.permissions.has(permission) ? true : denied(reason);
+  };
+}
+function guard(predicate) {
+  return predicate;
+}
 function withEphemeralFlag(flags) {
   if (flags == null) return discord_js.MessageFlags.Ephemeral;
   if (typeof flags === "number" || typeof flags === "bigint") {
@@ -25,86 +538,1647 @@ function normalizeEdit(input) {
   const { ephemeral: _ephemeral, flags: _flags, ...rest } = input;
   return rest;
 }
-function asEphemeral(input) {
-  if (typeof input === "string") return { content: input, ephemeral: true };
-  return { ...input, ephemeral: true };
+function asEphemeral(input) {
+  if (typeof input === "string") return { content: input, ephemeral: true };
+  return { ...input, ephemeral: true };
+}
+var BaseContext = class {
+  constructor(interaction) {
+    this.interaction = interaction;
+  }
+  interaction;
+  get client() {
+    return this.interaction.client;
+  }
+  get user() {
+    return this.interaction.user;
+  }
+  get member() {
+    return this.interaction.member;
+  }
+  get guild() {
+    return this.interaction.guild;
+  }
+  get guildId() {
+    return this.interaction.guildId;
+  }
+  get channel() {
+    return this.interaction.channel;
+  }
+  get channelId() {
+    return this.interaction.channelId;
+  }
+  get locale() {
+    return this.interaction.locale;
+  }
+  /** Whether the interaction is already deferred. */
+  get deferred() {
+    return this.interaction.deferred;
+  }
+  /** Whether the interaction already received an initial response. */
+  get replied() {
+    return this.interaction.replied;
+  }
+  /** Send the initial response to the interaction. */
+  reply(input) {
+    return this.interaction.reply(normalizeReply(input));
+  }
+  /** Reply, but always hidden to everyone except the invoking user. */
+  replyEphemeral(input) {
+    return this.reply(asEphemeral(input));
+  }
+  /** Acknowledge now and respond later via {@link editReply}. */
+  defer(options = {}) {
+    return this.interaction.deferReply(
+      options.ephemeral ? { flags: discord_js.MessageFlags.Ephemeral } : {}
+    );
+  }
+  /** Edit the original (or deferred) response. */
+  editReply(input) {
+    return this.interaction.editReply(normalizeEdit(input));
+  }
+  /** Add an additional message after the initial response. */
+  followUp(input) {
+    return this.interaction.followUp(normalizeReply(input));
+  }
+  /**
+   * State-aware send: replies, edits a deferred response, or follows up —
+   * whichever is valid given the current interaction state. The single method
+   * most handlers ever need.
+   */
+  async send(input) {
+    if (this.interaction.deferred) {
+      await this.editReply(input);
+    } else if (this.interaction.replied) {
+      await this.followUp(input);
+    } else {
+      await this.reply(input);
+    }
+  }
+  /** Get the configured {@link Embeds} factory — `client.embeds` or the default. */
+  getEmbeds() {
+    return this.interaction.client.embeds ?? defaultEmbeds;
+  }
+  /** State-aware send of a red error embed. Defaults to ephemeral. */
+  error(input, options = {}) {
+    return this.sendPreset("error", input, { ephemeral: options.ephemeral ?? true });
+  }
+  /** State-aware send of a green success embed. */
+  success(input, options = {}) {
+    return this.sendPreset("success", input, options);
+  }
+  /** State-aware send of a blue info embed. */
+  info(input, options = {}) {
+    return this.sendPreset("info", input, options);
+  }
+  /** State-aware send of a yellow warn embed. */
+  warn(input, options = {}) {
+    return this.sendPreset("warn", input, options);
+  }
+  /** Initial-reply variant of {@link error} (always `reply`, never `editReply`/`followUp`). */
+  replyError(input, options = {}) {
+    return this.replyPreset("error", input, { ephemeral: options.ephemeral ?? true });
+  }
+  /** Initial-reply variant of {@link success}. */
+  replySuccess(input, options = {}) {
+    return this.replyPreset("success", input, options);
+  }
+  /** Initial-reply variant of {@link info}. */
+  replyInfo(input, options = {}) {
+    return this.replyPreset("info", input, options);
+  }
+  /** Initial-reply variant of {@link warn}. */
+  replyWarn(input, options = {}) {
+    return this.replyPreset("warn", input, options);
+  }
+  sendPreset(level, input, options) {
+    const embed = this.getEmbeds().build(level, input);
+    return this.send({ embeds: [embed], ephemeral: options.ephemeral });
+  }
+  replyPreset(level, input, options) {
+    const embed = this.getEmbeds().build(level, input);
+    return this.reply({ embeds: [embed], ephemeral: options.ephemeral });
+  }
+};
+
+// src/cooldown.ts
+function normalizeCooldown(input) {
+  return typeof input === "number" ? { duration: input } : input;
+}
+function scopeKey(scope, actor) {
+  switch (scope) {
+    case "guild":
+      return `g:${actor.guildId ?? "dm"}`;
+    case "channel":
+      return `c:${actor.channelId ?? "dm"}`;
+    case "global":
+      return "global";
+    case "user":
+      return `u:${actor.userId}`;
+  }
+}
+function effectiveDuration(config, actor) {
+  if (config.exempt?.users?.includes(actor.userId) === true) return null;
+  if (config.exempt?.roles?.some((roleId) => actor.roleIds.includes(roleId)) === true) return null;
+  const userOverride = config.overrides?.users?.[actor.userId];
+  if (userOverride !== void 0) return userOverride;
+  const roleOverrides = config.overrides?.roles;
+  if (roleOverrides !== void 0) {
+    let best;
+    for (const roleId of actor.roleIds) {
+      const candidate = roleOverrides[roleId];
+      if (candidate !== void 0) best = best === void 0 ? candidate : Math.min(best, candidate);
+    }
+    if (best !== void 0) return best;
+  }
+  return config.duration;
+}
+function keyFor(bucket, config, actor) {
+  return `${bucket}|${scopeKey(config.scope ?? "user", actor)}`;
+}
+var CooldownManager = class {
+  hits = /* @__PURE__ */ new Map();
+  /** Number of tracked buckets. */
+  get size() {
+    return this.hits.size;
+  }
+  /**
+   * Check whether `actor` may use `bucket`, recording the use when allowed.
+   * Exempt actors and non-positive durations are always allowed (no record).
+   */
+  consume(bucket, input, actor, now = Date.now()) {
+    const config = normalizeCooldown(input);
+    const duration = effectiveDuration(config, actor);
+    if (duration === null || duration <= 0) return { allowed: true };
+    const key = keyFor(bucket, config, actor);
+    const last = this.hits.get(key);
+    if (last !== void 0 && now - last < duration) {
+      return { allowed: false, remaining: duration - (now - last) };
+    }
+    this.hits.set(key, now);
+    return { allowed: true };
+  }
+  /** Like {@link consume} but never records — a read-only check. */
+  peek(bucket, input, actor, now = Date.now()) {
+    const config = normalizeCooldown(input);
+    const duration = effectiveDuration(config, actor);
+    if (duration === null || duration <= 0) return { allowed: true };
+    const last = this.hits.get(keyFor(bucket, config, actor));
+    if (last !== void 0 && now - last < duration) {
+      return { allowed: false, remaining: duration - (now - last) };
+    }
+    return { allowed: true };
+  }
+  /** Clear a single actor's cooldown for a bucket. Returns whether one existed. */
+  reset(bucket, actor, scope = "user") {
+    return this.hits.delete(`${bucket}|${scopeKey(scope, actor)}`);
+  }
+  /** Drop every tracked cooldown. */
+  clear() {
+    this.hits.clear();
+  }
+};
+function formatCooldownMessage(config, remainingMs) {
+  if (typeof config.message === "function") return config.message(remainingMs);
+  if (typeof config.message === "string") return config.message;
+  const seconds = Math.max(1, Math.ceil(remainingMs / 1e3));
+  return `You're on cooldown \u2014 try again in ${seconds}s.`;
+}
+
+// src/context-menus.ts
+var UserContextMenuContext = class extends BaseContext {
+  /** The user the menu was invoked on. */
+  get targetUser() {
+    return this.interaction.targetUser;
+  }
+  /** The member version of the target, if available. */
+  get targetMember() {
+    return this.interaction.targetMember;
+  }
+};
+var MessageContextMenuContext = class extends BaseContext {
+  /** The message the menu was invoked on. */
+  get targetMessage() {
+    return this.interaction.targetMessage;
+  }
+};
+function baseJSON(meta, type) {
+  return {
+    type,
+    name: meta.name,
+    name_localizations: meta.nameLocalizations,
+    nsfw: meta.nsfw,
+    default_member_permissions: meta.defaultMemberPermissions == null ? meta.defaultMemberPermissions : new discord_js.PermissionsBitField(meta.defaultMemberPermissions).bitfield.toString(),
+    contexts: meta.guildOnly ? [discord_js.InteractionContextType.Guild] : void 0
+  };
+}
+function userCommand(config) {
+  const cooldown = config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0;
+  return {
+    kind: "userMenu",
+    name: config.name,
+    cooldown,
+    guards: config.guards,
+    toJSON: () => baseJSON(config, discord_js.ApplicationCommandType.User),
+    execute: async (interaction) => {
+      await config.run(new UserContextMenuContext(interaction));
+    }
+  };
+}
+function messageCommand(config) {
+  const cooldown = config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0;
+  return {
+    kind: "messageMenu",
+    name: config.name,
+    cooldown,
+    guards: config.guards,
+    toJSON: () => baseJSON(config, discord_js.ApplicationCommandType.Message),
+    execute: async (interaction) => {
+      await config.run(new MessageContextMenuContext(interaction));
+    }
+  };
+}
+var ContextMenuRegistry = class {
+  users = /* @__PURE__ */ new Map();
+  messages = /* @__PURE__ */ new Map();
+  logger;
+  cooldowns;
+  defaultCooldown;
+  defaultGuards = [];
+  onUsage;
+  /** Register one or more context-menu commands. */
+  add(...commands) {
+    for (const command2 of commands) {
+      if (command2.kind === "userMenu") this.users.set(command2.name, command2);
+      else this.messages.set(command2.name, command2);
+    }
+    return this;
+  }
+  /** Total number of registered context-menu commands. */
+  get size() {
+    return this.users.size + this.messages.size;
+  }
+  /** Every registered command, both kinds. */
+  all() {
+    return [...this.users.values(), ...this.messages.values()];
+  }
+  /** Serialise every command for the REST `applicationCommands` PUT body. */
+  toJSON() {
+    return this.all().map((c) => c.toJSON());
+  }
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  setCooldowns(manager, defaultCooldown) {
+    this.cooldowns = manager;
+    this.defaultCooldown = defaultCooldown;
+    return this;
+  }
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
+  setUsageHook(hook) {
+    this.onUsage = hook;
+    return this;
+  }
+  /** Dispatch a user-target interaction. */
+  async handleUser(interaction) {
+    const command2 = this.users.get(interaction.commandName);
+    if (command2 === void 0) return;
+    await this.dispatch(command2, interaction);
+  }
+  /** Dispatch a message-target interaction. */
+  async handleMessage(interaction) {
+    const command2 = this.messages.get(interaction.commandName);
+    if (command2 === void 0) return;
+    await this.dispatch(command2, interaction);
+  }
+  async dispatch(command2, interaction) {
+    this.logger?.debug("contextMenu", {
+      data: { kind: command2.kind, name: command2.name, user: interaction.user.id }
+    });
+    const cooldown = command2.cooldown ?? this.defaultCooldown;
+    if (cooldown !== void 0 && this.cooldowns !== void 0) {
+      const result = this.cooldowns.consume(
+        `${command2.kind}:${command2.name}`,
+        cooldown,
+        actorOf(interaction)
+      );
+      if (!result.allowed) {
+        await replyCooldown(interaction, cooldown, result.remaining);
+        return;
+      }
+    }
+    const guards = combineGuards(this.defaultGuards, command2.guards);
+    if (guards.length > 0) {
+      const guardResult = await runGuards(interaction, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("contextMenu denied", {
+          data: { name: command2.name, user: interaction.user.id, reason: guardResult.reason ?? "" }
+        });
+        await replyDenied(interaction, guardResult.reason);
+        return;
+      }
+    }
+    const start = Date.now();
+    try {
+      if (command2.kind === "userMenu") {
+        await command2.execute(interaction);
+      } else {
+        await command2.execute(interaction);
+      }
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        detail: command2.kind,
+        outcome: "success",
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        detail: command2.kind,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      interaction.client.emit("error", err);
+      try {
+        if (!interaction.replied && !interaction.deferred) {
+          await interaction.reply({
+            content: "Something went wrong.",
+            flags: discord_js.MessageFlags.Ephemeral
+          });
+        }
+      } catch {
+      }
+    }
+  }
+};
+function combineGuards(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function actorOf(interaction) {
+  const member = interaction.member;
+  let roleIds = [];
+  if (member !== null) {
+    const roles = member.roles;
+    roleIds = Array.isArray(roles) ? roles : [...roles.cache.keys()];
+  }
+  return {
+    userId: interaction.user.id,
+    roleIds,
+    guildId: interaction.guildId,
+    channelId: interaction.channelId
+  };
+}
+function clientEmbeds(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function replyCooldown(interaction, config, remaining) {
+  const content = formatCooldownMessage(config, remaining);
+  try {
+    if (interaction.deferred) await interaction.editReply({ content });
+    else if (interaction.replied) await interaction.followUp({ content, flags: discord_js.MessageFlags.Ephemeral });
+    else await interaction.reply({ content, flags: discord_js.MessageFlags.Ephemeral });
+  } catch {
+  }
+}
+async function replyDenied(interaction, reason) {
+  const embeds = clientEmbeds(interaction.client);
+  const text = reason ?? "You don't have permission to use this.";
+  try {
+    const payload = { embeds: [embeds.error(text)], flags: discord_js.MessageFlags.Ephemeral };
+    if (interaction.deferred) await interaction.editReply({ embeds: payload.embeds });
+    else if (interaction.replied) await interaction.followUp(payload);
+    else await interaction.reply(payload);
+  } catch {
+  }
+}
+
+// src/prefix-args.ts
+var SNOWFLAKE_RE = /^\d{15,21}$/;
+var USER_MENTION_RE = /^<@!?(\d{15,21})>$/;
+var CHANNEL_MENTION_RE = /^<#(\d{15,21})>$/;
+var ROLE_MENTION_RE = /^<@&(\d{15,21})>$/;
+function extractSnowflake(input) {
+  if (SNOWFLAKE_RE.test(input)) return input;
+  const m = USER_MENTION_RE.exec(input) ?? CHANNEL_MENTION_RE.exec(input) ?? ROLE_MENTION_RE.exec(input);
+  return m === null ? null : m[1] ?? null;
+}
+var PrefixArgsBuilder = class _PrefixArgsBuilder {
+  specs;
+  /** @internal */
+  constructor(specs = []) {
+    this.specs = specs;
+  }
+  /** A raw string token. */
+  string(name, options) {
+    return this.push({ name, kind: "string", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A whole integer. */
+  integer(name, options) {
+    return this.push({ name, kind: "integer", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A floating-point number. */
+  number(name, options) {
+    return this.push({ name, kind: "number", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A boolean (`true`/`yes`/`1`/`on` vs `false`/`no`/`0`/`off`). */
+  boolean(name, options) {
+    return this.push({ name, kind: "boolean", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A Discord snowflake id — accepts raw ids and `<@u>` / `<#c>` / `<@&r>` mentions. */
+  snowflake(name, options) {
+    return this.push({ name, kind: "snowflake", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** A duration like `"1h30m"` or `"1 saat"` parsed to milliseconds. */
+  duration(name, options) {
+    return this.push({ name, kind: "duration", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  /** The remainder of the message (everything after previous args). */
+  rest(name, options) {
+    return this.push({ name, kind: "rest", required: options?.required ?? false, defaultValue: options?.default });
+  }
+  push(spec) {
+    return new _PrefixArgsBuilder([...this.specs, spec]);
+  }
+  /** Compile this builder into a parser. */
+  compile() {
+    const specs = this.specs;
+    return {
+      specs,
+      parse(tokens, rest) {
+        const out = {};
+        let idx = 0;
+        for (let i = 0; i < specs.length; i++) {
+          const spec = specs[i];
+          if (spec.kind === "rest") {
+            const tail = idx === 0 ? rest : tokens.slice(idx).join(" ");
+            if (tail.length === 0) {
+              if (spec.required) return { ok: false, arg: spec.name, reason: `missing required argument "${spec.name}"` };
+              out[spec.name] = spec.defaultValue;
+            } else {
+              out[spec.name] = tail;
+            }
+            idx = tokens.length;
+            continue;
+          }
+          const token = tokens[idx];
+          if (token === void 0) {
+            if (spec.required) {
+              return { ok: false, arg: spec.name, reason: `missing required argument "${spec.name}"` };
+            }
+            out[spec.name] = spec.defaultValue;
+            continue;
+          }
+          const parsed = coerce(spec, token);
+          if (parsed.ok === false) return { ok: false, arg: spec.name, reason: parsed.reason };
+          out[spec.name] = parsed.value;
+          idx += 1;
+        }
+        return { ok: true, values: out };
+      }
+    };
+  }
+};
+function coerce(spec, token) {
+  switch (spec.kind) {
+    case "string":
+      return { ok: true, value: token };
+    case "integer": {
+      const n = Number(token);
+      if (!Number.isInteger(n)) return { ok: false, reason: `"${token}" is not an integer` };
+      return { ok: true, value: n };
+    }
+    case "number": {
+      const n = Number(token);
+      if (!Number.isFinite(n)) return { ok: false, reason: `"${token}" is not a number` };
+      return { ok: true, value: n };
+    }
+    case "boolean": {
+      const low = token.toLowerCase();
+      if (["true", "1", "yes", "on"].includes(low)) return { ok: true, value: true };
+      if (["false", "0", "no", "off"].includes(low)) return { ok: true, value: false };
+      return { ok: false, reason: `"${token}" is not a boolean` };
+    }
+    case "snowflake": {
+      const id = extractSnowflake(token);
+      if (id === null) return { ok: false, reason: `"${token}" is not a snowflake or mention` };
+      return { ok: true, value: id };
+    }
+    case "duration": {
+      const ms = parseDuration(token);
+      if (ms === null) return { ok: false, reason: `"${token}" is not a duration` };
+      return { ok: true, value: ms };
+    }
+    default:
+      return { ok: false, reason: `unknown arg kind for "${spec.name}"` };
+  }
+}
+function prefixArgs() {
+  return new PrefixArgsBuilder();
+}
+function normalisePayload(render) {
+  if (typeof render.setColor === "function" && typeof render.toJSON === "function") {
+    return { embeds: [render] };
+  }
+  if (Array.isArray(render)) {
+    return { embeds: render };
+  }
+  return render;
+}
+function controlsRow(page, pages, ns, controls, labels) {
+  const buttons = [];
+  if (controls === "first-prev-next-last") {
+    buttons.push(
+      new discord_js.ButtonBuilder().setCustomId(`${ns}:first`).setStyle(discord_js.ButtonStyle.Secondary).setLabel(labels.first).setDisabled(page === 0)
+    );
+  }
+  buttons.push(
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:prev`).setStyle(discord_js.ButtonStyle.Primary).setLabel(labels.prev).setDisabled(page === 0),
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:next`).setStyle(discord_js.ButtonStyle.Primary).setLabel(labels.next).setDisabled(page >= pages - 1)
+  );
+  if (controls === "first-prev-next-last") {
+    buttons.push(
+      new discord_js.ButtonBuilder().setCustomId(`${ns}:last`).setStyle(discord_js.ButtonStyle.Secondary).setLabel(labels.last).setDisabled(page >= pages - 1)
+    );
+  }
+  return new discord_js.ActionRowBuilder().addComponents(...buttons);
+}
+function resolveLabels2(input) {
+  return {
+    first: input?.first ?? "\xAB",
+    prev: input?.prev ?? "\u2039",
+    next: input?.next ?? "\u203A",
+    last: input?.last ?? "\xBB"
+  };
+}
+async function buildPaginatorPage(items, page, options) {
+  const pageSize = options.pageSize ?? 10;
+  const pages = Math.max(1, Math.ceil(items.length / pageSize));
+  const ns = options.namespace ?? "spk-page";
+  const controls = options.controls ?? "prev-next";
+  const labels = resolveLabels2(options.labels);
+  const slice = items.slice(page * pageSize, page * pageSize + pageSize);
+  const body = await options.render(slice, { page, pages });
+  const payload = normalisePayload(body);
+  const components = pages > 1 ? [controlsRow(page, pages, ns, controls, labels)] : [];
+  return { payload: { ...payload, components }, pages };
+}
+async function paginate(interaction, items, options) {
+  const pageSize = options.pageSize ?? 10;
+  const ns = options.namespace ?? "spk-page";
+  const controls = options.controls ?? "prev-next";
+  const labels = resolveLabels2(options.labels);
+  const allowedUser = options.user ?? interaction.user.id;
+  let page = 0;
+  const buildPage = async () => {
+    return buildPaginatorPage(items, page, { ...options, pageSize, namespace: ns, controls, labels });
+  };
+  const { payload: initial, pages } = await buildPage();
+  const sent = interaction.deferred ? await interaction.editReply(initial) : (await interaction.reply({
+    ...initial,
+    flags: options.ephemeral === true ? 64 : void 0
+  }), await interaction.fetchReply());
+  if (pages <= 1) return;
+  const collector = sent.createMessageComponentCollector({
+    componentType: discord_js.ComponentType.Button,
+    time: options.timeoutMs ?? 5 * 6e4,
+    filter: (i) => i.user.id === allowedUser && i.customId.startsWith(`${ns}:`)
+  });
+  collector.on("collect", async (button2) => {
+    const action = button2.customId.slice(ns.length + 1);
+    if (action === "first") page = 0;
+    else if (action === "prev") page = Math.max(0, page - 1);
+    else if (action === "next") page = Math.min(pages - 1, page + 1);
+    else if (action === "last") page = pages - 1;
+    const next = await buildPage();
+    await button2.update(next.payload).catch(() => void 0);
+  });
+  collector.on("end", async () => {
+    const disabledRow = controlsRow(page, pages, ns, controls, labels);
+    for (const c of disabledRow.components) c.setDisabled(true);
+    const { payload: final } = await buildPage();
+    await interaction.editReply({ ...final, components: [disabledRow] }).catch(() => void 0);
+  });
+}
+var STYLE_MAP = {
+  Primary: discord_js.ButtonStyle.Primary,
+  Secondary: discord_js.ButtonStyle.Secondary,
+  Success: discord_js.ButtonStyle.Success,
+  Danger: discord_js.ButtonStyle.Danger
+};
+function clientEmbeds2(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function confirm(interaction, options) {
+  const ns = options.namespace ?? "spk-confirm";
+  const confirmLabel = options.confirm?.label ?? "Confirm";
+  const cancelLabel = options.cancel?.label ?? "Cancel";
+  const confirmStyle = STYLE_MAP[options.confirm?.style ?? "Success"];
+  const cancelStyle = STYLE_MAP[options.cancel?.style ?? "Secondary"];
+  const user = options.user ?? interaction.user.id;
+  const ephemeral = options.ephemeral !== false;
+  const embeds = clientEmbeds2(interaction.client);
+  const promptEmbed = embeds.info(
+    options.title !== void 0 ? { title: options.title, description: options.body } : options.body
+  );
+  const row2 = new discord_js.ActionRowBuilder().addComponents(
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:yes`).setLabel(confirmLabel).setStyle(confirmStyle),
+    new discord_js.ButtonBuilder().setCustomId(`${ns}:no`).setLabel(cancelLabel).setStyle(cancelStyle)
+  );
+  const payload = { embeds: [promptEmbed], components: [row2] };
+  const sent = interaction.deferred ? await interaction.editReply(payload) : (await interaction.reply({
+    ...payload,
+    flags: ephemeral ? 64 : void 0
+  }), await interaction.fetchReply());
+  return new Promise((resolve) => {
+    const collector = sent.createMessageComponentCollector({
+      componentType: discord_js.ComponentType.Button,
+      time: options.timeoutMs ?? 3e4,
+      max: 1,
+      filter: (i) => i.user.id === user && i.customId.startsWith(`${ns}:`)
+    });
+    let outcome = null;
+    collector.on("collect", async (button2) => {
+      const action = button2.customId.slice(ns.length + 1);
+      outcome = {
+        confirmed: action === "yes",
+        reason: action === "yes" ? "confirm" : "cancel",
+        interaction: button2
+      };
+      await button2.deferUpdate().catch(() => void 0);
+    });
+    collector.on("end", async () => {
+      for (const c of row2.components) c.setDisabled(true);
+      await interaction.editReply({ embeds: [promptEmbed], components: [row2] }).catch(() => void 0);
+      resolve(outcome ?? { confirmed: false, reason: "timeout" });
+    });
+  });
+}
+var RANK = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: Number.POSITIVE_INFINITY
+};
+function formatValue(value) {
+  return typeof value === "string" ? value : String(value);
+}
+function consoleSink(entry) {
+  const scope = entry.scope !== void 0 ? ` [${entry.scope}]` : "";
+  let suffix = "";
+  if (entry.data !== void 0) {
+    const parts = Object.entries(entry.data).map(([k, v]) => `${k}=${formatValue(v)}`);
+    if (parts.length > 0) suffix = ` ${parts.join(" ")}`;
+  }
+  const line = `${entry.timestamp.toISOString()} ${entry.level.toUpperCase()}${scope} ${entry.message}${suffix}`;
+  const write = entry.level === "warn" || entry.level === "error" ? console.error : console.log;
+  write(line);
+  if (entry.error !== void 0) write(entry.error.stack ?? String(entry.error));
+}
+function jsonlSink(path$1, options = {}) {
+  const min = options.minLevel ?? "debug";
+  let dirReady = false;
+  let chain = Promise.resolve();
+  return (entry) => {
+    if (RANK[entry.level] < RANK[min]) return;
+    const record = {
+      ...entry,
+      timestamp: entry.timestamp.toISOString(),
+      error: entry.error ? { name: entry.error.name, message: entry.error.message, stack: entry.error.stack } : void 0
+    };
+    const line = `${JSON.stringify(record)}
+`;
+    chain = chain.then(async () => {
+      try {
+        if (!dirReady) {
+          await promises.mkdir(path.dirname(path$1), { recursive: true });
+          dirReady = true;
+        }
+        await promises.appendFile(path$1, line, "utf8");
+      } catch {
+      }
+    });
+  };
+}
+function webhookSink(options) {
+  const min = options.minLevel ?? "warn";
+  return (entry) => {
+    if (RANK[entry.level] < RANK[min]) return;
+    const color = entry.level === "error" ? 15747655 : entry.level === "warn" ? 16361509 : 3447003;
+    const fields = [];
+    if (entry.scope !== void 0) fields.push({ name: "Scope", value: entry.scope, inline: true });
+    if (entry.data !== void 0) {
+      for (const [k, v] of Object.entries(entry.data)) {
+        fields.push({ name: k, value: formatValue(v).slice(0, 1e3), inline: true });
+      }
+    }
+    const desc = entry.error?.stack !== void 0 ? `${entry.message}
+\`\`\`
+${entry.error.stack.slice(0, 1800)}
+\`\`\`` : entry.message;
+    const body = {
+      username: options.username ?? "spearkit",
+      embeds: [
+        {
+          title: `[${entry.level.toUpperCase()}] ${entry.message.slice(0, 240)}`,
+          description: desc.slice(0, 4e3),
+          color,
+          timestamp: entry.timestamp.toISOString(),
+          fields: fields.slice(0, 25)
+        }
+      ]
+    };
+    void fetch(options.url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    }).catch(() => void 0);
+  };
+}
+function resolveTransports(options) {
+  if (options.transports !== void 0 && options.transports.length > 0) return options.transports;
+  if (options.sink !== void 0) return [options.sink];
+  return [consoleSink];
+}
+var Logger = class _Logger {
+  state;
+  /** The scope prefix applied to every entry, if any. */
+  scope;
+  constructor(options = {}) {
+    this.state = {
+      threshold: options.level ?? "info",
+      transports: resolveTransports(options)
+    };
+    this.scope = options.scope;
+  }
+  /** The current minimum threshold. */
+  get level() {
+    return this.state.threshold;
+  }
+  /** Change the threshold for this logger and every child sharing its state. */
+  setLevel(level) {
+    this.state.threshold = level;
+    return this;
+  }
+  /** Replace the transport list for this logger and every child sharing its state. */
+  setTransports(transports) {
+    this.state.transports = transports;
+    return this;
+  }
+  /** Append a transport to the existing list. */
+  addTransport(sink) {
+    this.state.transports = [...this.state.transports, sink];
+    return this;
+  }
+  /** Whether an entry of `level` would currently be emitted. */
+  enabled(level) {
+    return RANK[level] >= RANK[this.state.threshold];
+  }
+  /** A child logger with an extra scope segment, sharing this logger's state. */
+  child(scope) {
+    const combined = this.scope !== void 0 ? `${this.scope}:${scope}` : scope;
+    const child = new _Logger({ scope: combined });
+    child.state = this.state;
+    return child;
+  }
+  /** Emit an entry at an explicit level. */
+  log(level, message, options) {
+    if (!this.enabled(level)) return;
+    const entry = {
+      level,
+      message,
+      scope: this.scope,
+      timestamp: /* @__PURE__ */ new Date(),
+      error: options?.error,
+      data: options?.data
+    };
+    for (const sink of this.state.transports) {
+      try {
+        sink(entry);
+      } catch {
+      }
+    }
+  }
+  /** Verbose diagnostics, off by default. */
+  debug(message, options) {
+    this.log("debug", message, options);
+  }
+  /** Normal operational messages. */
+  info(message, options) {
+    this.log("info", message, options);
+  }
+  /** Recoverable problems worth attention. */
+  warn(message, options) {
+    this.log("warn", message, options);
+  }
+  /** Failures. Attach the cause via `{ error }`. */
+  error(message, options) {
+    this.log("error", message, options);
+  }
+};
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+function stripInlineComment(value) {
+  const match = /\s#/.exec(value);
+  return match !== null ? value.slice(0, match.index).trimEnd() : value;
+}
+function unquote(raw) {
+  if (raw.length >= 2) {
+    const quote = raw[0];
+    if ((quote === '"' || quote === "'") && raw.endsWith(quote)) {
+      const inner = raw.slice(1, -1);
+      return quote === '"' ? inner.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	") : inner;
+    }
+  }
+  return stripInlineComment(raw);
+}
+function parseEnv(content) {
+  const out = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) continue;
+    const body = line.startsWith("export ") ? line.slice(7).trimStart() : line;
+    const eq = body.indexOf("=");
+    if (eq <= 0) continue;
+    const key = body.slice(0, eq).trim();
+    if (key.length === 0) continue;
+    out[key] = unquote(body.slice(eq + 1).trim());
+  }
+  return out;
+}
+function loadEnv(options = {}) {
+  const path$1 = options.path ?? path.join(process.cwd(), ".env");
+  let content;
+  try {
+    content = fs.readFileSync(path$1, "utf8");
+  } catch {
+    return {};
+  }
+  const parsed = parseEnv(content);
+  for (const [key, value] of Object.entries(parsed)) {
+    if (options.override === true || process.env[key] === void 0) {
+      process.env[key] = value;
+    }
+  }
+  return parsed;
+}
+var TRUTHY = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
+var FALSY = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
+function read(key) {
+  const value = process.env[key];
+  return value !== void 0 && value !== "" ? value : void 0;
+}
+function envString(key, fallback) {
+  return read(key) ?? fallback;
+}
+function envNumber(key, fallback) {
+  const value = read(key);
+  if (value === void 0) return fallback;
+  const parsed = Number(value);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+function envBoolean(key, fallback) {
+  const value = read(key)?.toLowerCase();
+  if (value === void 0) return fallback;
+  if (TRUTHY.has(value)) return true;
+  if (FALSY.has(value)) return false;
+  return fallback;
+}
+function envRequire(key) {
+  const value = read(key);
+  if (value === void 0) {
+    throw new Error(`spearkit: required environment variable "${key}" is missing or empty`);
+  }
+  return value;
+}
+var env = {
+  string: envString,
+  number: envNumber,
+  boolean: envBoolean,
+  require: envRequire
+};
+
+// src/scheduler.ts
+var ALIASES = {
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+  "@monthly": "0 0 1 * *",
+  "@weekly": "0 0 * * 0",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly": "0 * * * *"
+};
+function parseField(spec, min, max, label) {
+  const set = /* @__PURE__ */ new Set();
+  for (const part of spec.split(",")) {
+    let range = part;
+    let step = 1;
+    const slash = part.indexOf("/");
+    if (slash >= 0) {
+      step = Number(part.slice(slash + 1));
+      range = part.slice(0, slash);
+      if (!Number.isInteger(step) || step <= 0) {
+        throw new Error(`spearkit: invalid step in cron ${label} field "${part}"`);
+      }
+    }
+    let lo;
+    let hi;
+    if (range === "*") {
+      lo = min;
+      hi = max;
+    } else if (range.includes("-")) {
+      const dash = range.indexOf("-");
+      lo = Number(range.slice(0, dash));
+      hi = Number(range.slice(dash + 1));
+    } else {
+      lo = Number(range);
+      hi = lo;
+    }
+    if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo < min || hi > max || lo > hi) {
+      throw new Error(`spearkit: cron ${label} field out of range ${min}-${max}: "${part}"`);
+    }
+    for (let value = lo; value <= hi; value += step) set.add(value);
+  }
+  return set;
+}
+var CronExpression = class {
+  /** The original expression string. */
+  source;
+  minutes;
+  hours;
+  daysOfMonth;
+  months;
+  daysOfWeek;
+  domRestricted;
+  dowRestricted;
+  constructor(expression) {
+    const trimmed = expression.trim();
+    const normalized = ALIASES[trimmed] ?? trimmed;
+    const parts = normalized.split(/\s+/);
+    if (parts.length !== 5) {
+      throw new Error(`spearkit: cron expression must have 5 fields, got "${expression}"`);
+    }
+    const [minute, hour, dom, month, dow] = parts;
+    if (minute === void 0 || hour === void 0 || dom === void 0 || month === void 0 || dow === void 0) {
+      throw new Error(`spearkit: invalid cron expression "${expression}"`);
+    }
+    this.source = expression;
+    this.minutes = parseField(minute, 0, 59, "minute");
+    this.hours = parseField(hour, 0, 23, "hour");
+    this.daysOfMonth = parseField(dom, 1, 31, "day-of-month");
+    this.months = parseField(month, 1, 12, "month");
+    const weekdays = parseField(dow, 0, 7, "day-of-week");
+    if (weekdays.has(7)) {
+      weekdays.delete(7);
+      weekdays.add(0);
+    }
+    this.daysOfWeek = weekdays;
+    this.domRestricted = dom !== "*";
+    this.dowRestricted = dow !== "*";
+  }
+  dayMatches(date) {
+    const dom = this.daysOfMonth.has(date.getDate());
+    const dow = this.daysOfWeek.has(date.getDay());
+    if (this.domRestricted && this.dowRestricted) return dom || dow;
+    if (this.domRestricted) return dom;
+    if (this.dowRestricted) return dow;
+    return true;
+  }
+  /** The next time strictly after `from` (default now) that matches. */
+  next(from = /* @__PURE__ */ new Date()) {
+    const date = new Date(from.getTime());
+    date.setSeconds(0, 0);
+    date.setMinutes(date.getMinutes() + 1);
+    for (let guard2 = 0; guard2 < 1e5; guard2++) {
+      if (!this.months.has(date.getMonth() + 1)) {
+        date.setMonth(date.getMonth() + 1, 1);
+        date.setHours(0, 0, 0, 0);
+        continue;
+      }
+      if (!this.dayMatches(date)) {
+        date.setDate(date.getDate() + 1);
+        date.setHours(0, 0, 0, 0);
+        continue;
+      }
+      if (!this.hours.has(date.getHours())) {
+        date.setHours(date.getHours() + 1, 0, 0, 0);
+        continue;
+      }
+      if (!this.minutes.has(date.getMinutes())) {
+        date.setMinutes(date.getMinutes() + 1, 0, 0);
+        continue;
+      }
+      return new Date(date.getTime());
+    }
+    throw new Error(`spearkit: cron expression "${this.source}" has no upcoming match`);
+  }
+};
+function cron(expression) {
+  return new CronExpression(expression);
+}
+function task(config) {
+  if (config.cron === void 0 && config.interval === void 0) {
+    throw new Error(`spearkit: task "${config.name}" needs a cron expression or an interval`);
+  }
+  if (config.interval !== void 0 && config.interval <= 0) {
+    throw new Error(`spearkit: task "${config.name}" interval must be positive`);
+  }
+  return {
+    kind: "task",
+    name: config.name,
+    interval: config.interval,
+    cron: config.cron !== void 0 ? new CronExpression(config.cron) : void 0,
+    runOnStart: config.runOnStart ?? false,
+    run: config.run
+  };
+}
+var MAX_TIMEOUT = 2147483647;
+var TaskScheduler = class {
+  tasks = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Map();
+  running = false;
+  client;
+  logger;
+  reconcilers = [];
+  /** Number of registered tasks. */
+  get size() {
+    return this.tasks.size;
+  }
+  /** Whether the scheduler is currently running. */
+  get active() {
+    return this.running;
+  }
+  /** Every registered task. */
+  list() {
+    return [...this.tasks.values()];
+  }
+  /** Attach a logger for task error reporting. */
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  /** Register one or more tasks. If already running, they are scheduled now. */
+  add(...tasks) {
+    for (const task2 of tasks) {
+      this.tasks.set(task2.name, task2);
+      if (this.running) this.begin(task2);
+    }
+    return this;
+  }
+  /** Remove a task and cancel its timer. */
+  remove(name) {
+    this.cancel(name);
+    return this.tasks.delete(name);
+  }
+  /**
+   * Schedule a one-shot job: run `fn` once after `ms` milliseconds, then forget.
+   * Returns a cancel handle. Replaces hand-rolled `setTimeout` calls for things
+   * like "remind the moderator in 10 minutes if no claim happened".
+   */
+  delay(name, ms, fn) {
+    const key = `delay:${name}`;
+    this.cancel(key);
+    const timer = setTimeout(async () => {
+      this.timers.delete(key);
+      try {
+        await fn();
+      } catch (error) {
+        this.logger?.error(`delay "${name}" failed`, { error: toError(error) });
+      }
+    }, Math.max(0, ms));
+    if (typeof timer.unref === "function") timer.unref();
+    this.timers.set(key, timer);
+    return {
+      cancel: () => {
+        const had = this.timers.has(key);
+        this.cancel(key);
+        return had;
+      }
+    };
+  }
+  /**
+   * Schedule a series of follow-up fires from a single start point. Each
+   * delay is measured from "now"; the callback receives the index of the
+   * fire. Generalises the 10s/30s/60s retry pattern in real bots.
+   */
+  followUp(name, delays, fn) {
+    const keys = delays.map((_, i) => `followUp:${name}:${i}`);
+    for (const key of keys) this.cancel(key);
+    delays.forEach((delay, i) => {
+      const key = keys[i];
+      const timer = setTimeout(async () => {
+        this.timers.delete(key);
+        try {
+          await fn(i);
+        } catch (error) {
+          this.logger?.error(`followUp "${name}" fire ${i} failed`, { error: toError(error) });
+        }
+      }, Math.max(0, delay));
+      if (typeof timer.unref === "function") timer.unref();
+      this.timers.set(key, timer);
+    });
+    return {
+      cancel: () => {
+        let any = false;
+        for (const key of keys) {
+          if (this.timers.has(key)) any = true;
+          this.cancel(key);
+        }
+        return any;
+      }
+    };
+  }
+  /**
+   * Register a once-on-ready reconciler — runs the first time the scheduler
+   * starts (typically when the client becomes ready) and never again. Use
+   * for restart-recovery work like closing orphaned voice sessions or
+   * reapplying cached channel state.
+   */
+  reconcile(name, fn) {
+    if (this.running && this.client !== void 0) {
+      void this.runReconciler(name, fn, this.client);
+    } else {
+      this.reconcilers.push({ name, run: fn });
+    }
+  }
+  async runReconciler(name, run, client) {
+    this.logger?.debug("reconcile", { data: { name } });
+    try {
+      await run(client);
+    } catch (error) {
+      this.logger?.error(`reconciler "${name}" failed`, { error: toError(error) });
+    }
+  }
+  /** Start every task. Safe to call once; later calls are ignored. */
+  start(client) {
+    if (this.running) return;
+    this.client = client;
+    this.running = true;
+    for (const task2 of this.tasks.values()) this.begin(task2);
+    const pending = this.reconcilers.splice(0);
+    for (const { name, run } of pending) void this.runReconciler(name, run, client);
+  }
+  /** Stop the scheduler and cancel every pending timer. */
+  stop() {
+    this.running = false;
+    for (const name of [...this.timers.keys()]) this.cancel(name);
+  }
+  cancel(name) {
+    const timer = this.timers.get(name);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.timers.delete(name);
+    }
+  }
+  begin(task2) {
+    if (task2.runOnStart) void this.runTask(task2);
+    this.scheduleNext(task2);
+  }
+  delayFor(task2) {
+    if (task2.interval !== void 0) return task2.interval;
+    if (task2.cron !== void 0) return Math.max(0, task2.cron.next().getTime() - Date.now());
+    return MAX_TIMEOUT;
+  }
+  scheduleNext(task2) {
+    if (!this.running) return;
+    this.arm(task2.name, this.delayFor(task2), () => {
+      void this.runTask(task2);
+      this.scheduleNext(task2);
+    });
+  }
+  arm(name, delay, fire) {
+    if (delay > MAX_TIMEOUT) {
+      const timer2 = setTimeout(() => this.arm(name, delay - MAX_TIMEOUT, fire), MAX_TIMEOUT);
+      if (typeof timer2.unref === "function") timer2.unref();
+      this.timers.set(name, timer2);
+      return;
+    }
+    const timer = setTimeout(fire, Math.max(0, delay));
+    if (typeof timer.unref === "function") timer.unref();
+    this.timers.set(name, timer);
+  }
+  async runTask(task2) {
+    if (this.client === void 0) return;
+    this.logger?.debug("task", { data: { task: task2.name } });
+    try {
+      await task2.run(this.client);
+    } catch (error) {
+      this.logger?.error(`task "${task2.name}" failed`, { error: toError(error) });
+    }
+  }
+};
+
+// src/prefix.ts
+function prefixCommand(config) {
+  const parser = config.args !== void 0 ? config.args(prefixArgs()).compile() : void 0;
+  return {
+    kind: "prefixCommand",
+    name: config.name,
+    aliases: config.aliases ?? [],
+    description: config.description,
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    guards: config.guards,
+    parser,
+    run: async (ctx) => {
+      await config.run(ctx);
+    }
+  };
 }
-var BaseContext = class {
-  constructor(interaction) {
-    this.interaction = interaction;
+var PrefixContext = class {
+  constructor(message, commandName, args, rest, options = {}) {
+    this.message = message;
+    this.commandName = commandName;
+    this.args = args;
+    this.rest = rest;
+    this.options = options;
   }
-  interaction;
+  message;
+  commandName;
+  args;
+  rest;
+  options;
   get client() {
-    return this.interaction.client;
+    return this.message.client;
   }
-  get user() {
-    return this.interaction.user;
+  get author() {
+    return this.message.author;
   }
   get member() {
-    return this.interaction.member;
+    return this.message.member;
   }
   get guild() {
-    return this.interaction.guild;
+    return this.message.guild;
   }
   get guildId() {
-    return this.interaction.guildId;
+    return this.message.guildId;
   }
   get channel() {
-    return this.interaction.channel;
+    return this.message.channel;
   }
   get channelId() {
-    return this.interaction.channelId;
+    return this.message.channelId;
   }
-  get locale() {
-    return this.interaction.locale;
+  /** Reply to the triggering message. */
+  reply(content) {
+    return this.message.reply(content);
   }
-  /** Whether the interaction is already deferred. */
-  get deferred() {
-    return this.interaction.deferred;
+  /** Send a message to the same channel (no reply reference). */
+  async send(content) {
+    const channel = this.message.channel;
+    if ("send" in channel) return channel.send(content);
+    return void 0;
   }
-  /** Whether the interaction already received an initial response. */
-  get replied() {
-    return this.interaction.replied;
+};
+function resolveOptions(input) {
+  if (typeof input === "string") return { prefixes: [input], mention: true, ignoreBots: true, caseInsensitive: true };
+  if (Array.isArray(input)) {
+    return { prefixes: [...input], mention: true, ignoreBots: true, caseInsensitive: true };
   }
-  /** Send the initial response to the interaction. */
-  reply(input) {
-    return this.interaction.reply(normalizeReply(input));
+  const options = input;
+  const prefix = options.prefix ?? [];
+  return {
+    prefixes: typeof prefix === "string" ? [prefix] : [...prefix],
+    mention: options.mention ?? true,
+    ignoreBots: options.ignoreBots ?? true,
+    caseInsensitive: options.caseInsensitive ?? true
+  };
+}
+function actorFromMessage(message) {
+  const member = message.member;
+  const roleIds = member !== null ? [...member.roles.cache.keys()] : [];
+  return {
+    userId: message.author.id,
+    roleIds,
+    guildId: message.guildId,
+    channelId: message.channelId
+  };
+}
+var PrefixRegistry = class {
+  commands = /* @__PURE__ */ new Map();
+  lookup = /* @__PURE__ */ new Map();
+  options = {
+    prefixes: [],
+    mention: true,
+    ignoreBots: true,
+    caseInsensitive: true
+  };
+  logger;
+  cooldowns;
+  defaultCooldown;
+  errorHandler;
+  defaultGuards = [];
+  onUsage;
+  /** Configure prefixes and matching behaviour. */
+  setOptions(input) {
+    this.options = resolveOptions(input);
+    return this;
   }
-  /** Reply, but always hidden to everyone except the invoking user. */
-  replyEphemeral(input) {
-    return this.reply(asEphemeral(input));
+  /** Attach a logger for dispatch tracing and error reporting. */
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
   }
-  /** Acknowledge now and respond later via {@link editReply}. */
-  defer(options = {}) {
-    return this.interaction.deferReply(
-      options.ephemeral ? { flags: discord_js.MessageFlags.Ephemeral } : {}
-    );
+  /** Attach a hook called after each successful prefix command run. */
+  setUsageHook(hook) {
+    this.onUsage = hook;
+    return this;
   }
-  /** Edit the original (or deferred) response. */
-  editReply(input) {
-    return this.interaction.editReply(normalizeEdit(input));
+  /** Share a cooldown manager and an optional default cooldown. */
+  setCooldowns(manager, defaultCooldown) {
+    this.cooldowns = manager;
+    this.defaultCooldown = defaultCooldown;
+    return this;
   }
-  /** Add an additional message after the initial response. */
-  followUp(input) {
-    return this.interaction.followUp(normalizeReply(input));
+  /** Guards that run before every prefix command's own guards. */
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
+  /** Set the handler used when a prefix command throws. */
+  onError(handler) {
+    this.errorHandler = handler;
+    return this;
+  }
+  /** Register one or more prefix commands (and their aliases). */
+  add(...commands) {
+    for (const command2 of commands) {
+      this.commands.set(command2.name, command2);
+      this.index(command2.name, command2);
+      for (const alias of command2.aliases) this.index(alias, command2);
+    }
+    return this;
+  }
+  index(key, command2) {
+    this.lookup.set(this.options.caseInsensitive ? key.toLowerCase() : key, command2);
+  }
+  /** Look up a command by name or alias. */
+  get(nameOrAlias) {
+    return this.lookup.get(this.options.caseInsensitive ? nameOrAlias.toLowerCase() : nameOrAlias);
+  }
+  /** Number of registered commands (excluding aliases). */
+  get size() {
+    return this.commands.size;
+  }
+  /** Every registered command. */
+  list() {
+    return [...this.commands.values()];
+  }
+  /** Strip a matching prefix (or bot mention) from `content`, or return `null`. */
+  stripPrefix(content, botId) {
+    for (const prefix of this.options.prefixes) {
+      if (prefix.length > 0 && content.startsWith(prefix)) return content.slice(prefix.length);
+    }
+    if (this.options.mention && botId !== void 0) {
+      const match = /^<@!?(\d+)>\s*/.exec(content);
+      if (match !== null && match[1] === botId) return content.slice(match[0].length);
+    }
+    return null;
   }
   /**
-   * State-aware send: replies, edits a deferred response, or follows up —
-   * whichever is valid given the current interaction state. The single method
-   * most handlers ever need.
+   * Parse and dispatch a message. Returns `true` when a command ran (or was
+   * blocked by a cooldown), `false` when the message was not a prefix command.
    */
-  async send(input) {
-    if (this.interaction.deferred) {
-      await this.editReply(input);
-    } else if (this.interaction.replied) {
-      await this.followUp(input);
-    } else {
-      await this.reply(input);
+  async handle(message) {
+    if (this.options.prefixes.length === 0 && !this.options.mention) return false;
+    if (this.options.ignoreBots && message.author.bot) return false;
+    const stripped = this.stripPrefix(message.content, message.client.user?.id);
+    if (stripped === null) return false;
+    const trimmed = stripped.trimStart();
+    const match = /^(\S+)\s*([\s\S]*)$/.exec(trimmed);
+    if (match === null) return false;
+    const name = match[1] ?? "";
+    const rest = match[2] ?? "";
+    const command2 = this.get(name);
+    if (command2 === void 0) return false;
+    this.logger?.debug("prefix", { data: { command: command2.name, user: message.author.id } });
+    const cooldown = command2.cooldown ?? this.defaultCooldown;
+    if (cooldown !== void 0 && this.cooldowns !== void 0) {
+      const result = this.cooldowns.consume(`prefix:${command2.name}`, cooldown, actorFromMessage(message));
+      if (!result.allowed) {
+        await message.reply(formatCooldownMessage(cooldown, result.remaining)).catch(() => void 0);
+        return true;
+      }
+    }
+    const guards = combineGuards2(this.defaultGuards, command2.guards);
+    if (guards.length > 0) {
+      const guardCtx = guardContextFromMessage(message);
+      const guardResult = await runGuards(guardCtx, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("prefix denied", {
+          data: {
+            command: command2.name,
+            user: message.author.id,
+            reason: guardResult.reason ?? ""
+          }
+        });
+        await replyDeniedMessage(message, guardResult.reason);
+        return true;
+      }
+    }
+    const args = rest.length > 0 ? rest.split(/\s+/) : [];
+    let options = {};
+    if (command2.parser !== void 0) {
+      const parsed = command2.parser.parse(args, rest);
+      if (!parsed.ok) {
+        this.logger?.debug("prefix arg error", {
+          data: { command: command2.name, user: message.author.id, arg: parsed.arg, reason: parsed.reason }
+        });
+        const embeds = clientEmbeds3(message.client);
+        await message.reply({ embeds: [embeds.error(`Argument \`${parsed.arg}\`: ${parsed.reason}`)] }).catch(() => void 0);
+        return true;
+      }
+      options = parsed.values;
+    }
+    const start = Date.now();
+    try {
+      await command2.run(new PrefixContext(message, name, args, rest, options));
+      this.onUsage?.({
+        type: "prefix",
+        name: command2.name,
+        outcome: "success",
+        durationMs: Date.now() - start,
+        userId: message.author.id,
+        userTag: message.author.tag,
+        guildId: message.guildId,
+        channelId: message.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+    } catch (error) {
+      const err = toError(error);
+      this.logger?.error(`prefix command "${command2.name}" failed`, { error: err });
+      this.onUsage?.({
+        type: "prefix",
+        name: command2.name,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: message.author.id,
+        userTag: message.author.tag,
+        guildId: message.guildId,
+        channelId: message.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
+      if (this.errorHandler !== void 0) await this.errorHandler(err, message);
+    }
+    return true;
+  }
+};
+function combineGuards2(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function guardContextFromMessage(message) {
+  return {
+    client: message.client,
+    user: message.author,
+    member: message.member,
+    guild: message.guild,
+    guildId: message.guildId,
+    channelId: message.channelId
+  };
+}
+function clientEmbeds3(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function replyDeniedMessage(message, reason) {
+  const embeds = clientEmbeds3(message.client);
+  const text = reason ?? "You don't have permission to use this.";
+  await message.reply({ embeds: [embeds.error(text)] }).catch(() => void 0);
+}
+var MemoryUsageStore = class {
+  constructor(limit = Number.POSITIVE_INFINITY) {
+    this.limit = limit;
+  }
+  limit;
+  events = [];
+  record(event2) {
+    this.events.push(event2);
+    if (this.events.length > this.limit) this.events.splice(0, this.events.length - this.limit);
+  }
+  all() {
+    return this.events;
+  }
+  /** Total recorded events. */
+  get size() {
+    return this.events.length;
+  }
+  /** Events recorded for a given user id. */
+  byUser(userId) {
+    return this.events.filter((event2) => event2.userId === userId);
+  }
+  /** Forget everything. */
+  clear() {
+    this.events.length = 0;
+  }
+};
+var JsonFileUsageStore = class {
+  constructor(path) {
+    this.path = path;
+  }
+  path;
+  async record(event2) {
+    const line = `${JSON.stringify({ ...event2, timestamp: event2.timestamp.toISOString() })}
+`;
+    await promises.mkdir(path.dirname(this.path), { recursive: true });
+    await promises.appendFile(this.path, line, "utf8");
+  }
+  async all() {
+    let content;
+    try {
+      content = await promises.readFile(this.path, "utf8");
+    } catch {
+      return [];
     }
+    const events = [];
+    for (const line of content.split("\n")) {
+      if (line.trim().length === 0) continue;
+      const parsed = JSON.parse(line);
+      events.push({ ...parsed, timestamp: new Date(parsed.timestamp) });
+    }
+    return events;
+  }
+};
+function formatUsage(event2) {
+  const who = event2.userTag ?? (event2.userId !== void 0 ? `<@${event2.userId}>` : "unknown");
+  const where = event2.channelId !== void 0 && event2.channelId !== null ? ` in <#${event2.channelId}>` : "";
+  const detail = event2.detail !== void 0 ? ` \u2014 ${event2.detail}` : "";
+  return `\`${event2.type}\` **${event2.name}** by ${who}${where}${detail}`;
+}
+var UsageTracker = class {
+  /** The configured store, if any. Directly queryable. */
+  store;
+  reporter;
+  client;
+  logger;
+  /** Whether anything will happen on {@link track}. */
+  get enabled() {
+    return this.store !== void 0 || this.reporter !== void 0;
+  }
+  /** @internal Used by the client to resolve report channels. */
+  setClient(client) {
+    this.client = client;
+    return this;
+  }
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  /** Persist events to a store (a database). */
+  setStore(store) {
+    this.store = store;
+    return this;
+  }
+  /** Mirror events into a Discord channel. */
+  reportTo(channelId, format = formatUsage) {
+    this.reporter = { channelId, format };
+    return this;
   }
-  /** State-aware ephemeral error message. */
-  error(message) {
-    return this.send(asEphemeral(message));
+  /** Record a use. Returns immediately; storing/reporting happen in the background. */
+  track(event2) {
+    if (!this.enabled) return;
+    void this.run(event2);
+  }
+  async run(event2) {
+    if (this.store !== void 0) {
+      try {
+        await this.store.record(event2);
+      } catch (error) {
+        this.logger?.error("usage store failed", { error: toError(error) });
+      }
+    }
+    if (this.reporter !== void 0 && this.client !== void 0) {
+      try {
+        const cache = this.client.channels.cache.get(this.reporter.channelId);
+        const channel = cache ?? await this.client.channels.fetch(this.reporter.channelId);
+        if (channel !== null && "send" in channel) {
+          await channel.send(this.reporter.format(event2));
+        }
+      } catch (error) {
+        this.logger?.error("usage report failed", { error: toError(error) });
+      }
+    }
   }
 };
 function makeOption(type, config) {
@@ -286,6 +2360,10 @@ var SlashCommand = class {
   json;
   executor;
   autocompleter;
+  /** Resolved cooldown configuration for this command, if any. */
+  cooldown;
+  /** Resolved guard list for this command, if any. */
+  guards;
   /** @internal */
   constructor(spec) {
     this.name = spec.name;
@@ -293,6 +2371,8 @@ var SlashCommand = class {
     this.json = spec.json;
     this.executor = spec.executor;
     this.autocompleter = spec.autocompleter;
+    this.cooldown = spec.cooldown;
+    this.guards = spec.guards;
   }
   /** Serialise to the discord REST chat-input command payload. */
   toJSON() {
@@ -307,7 +2387,7 @@ var SlashCommand = class {
     return this.autocompleter(interaction);
   }
 };
-function resolveOptions(interaction, options) {
+function resolveOptions2(interaction, options) {
   const resolved = {};
   for (const [name, def] of Object.entries(options)) {
     resolved[name] = readOption(interaction.options, name, def);
@@ -327,7 +2407,7 @@ function makeAutocompleter(options) {
     if (!interaction.responded) await ctx.respond(choices);
   };
 }
-function baseJSON(meta, options) {
+function baseJSON2(meta, options) {
   return {
     type: discord_js.ApplicationCommandType.ChatInput,
     name: meta.name,
@@ -362,22 +2442,24 @@ function command(config) {
   const options = config.options ?? {};
   const { run } = config;
   const executor = async (interaction) => {
-    const resolved = resolveOptions(interaction, options);
+    const resolved = resolveOptions2(interaction, options);
     await run(new CommandContext(interaction, resolved));
   };
   return new SlashCommand({
     name: config.name,
-    json: baseJSON(config, leafOptionsJSON(options)),
+    json: baseJSON2(config, leafOptionsJSON(options)),
     hasAutocomplete: optionsHaveAutocomplete(options),
     executor,
-    autocompleter: makeAutocompleter(options)
+    autocompleter: makeAutocompleter(options),
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    guards: config.guards
   });
 }
 function subcommand(config) {
   const options = config.options ?? {};
   const { run } = config;
   const execute = async (interaction) => {
-    const resolved = resolveOptions(interaction, options);
+    const resolved = resolveOptions2(interaction, options);
     await run(new CommandContext(interaction, resolved));
   };
   return {
@@ -438,15 +2520,22 @@ function commandGroup(config) {
   };
   return new SlashCommand({
     name: config.name,
-    json: baseJSON(config, options),
+    json: baseJSON2(config, options),
     hasAutocomplete,
     executor,
-    autocompleter
+    autocompleter,
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    guards: config.guards
   });
 }
 var CommandRegistry = class {
   commands = /* @__PURE__ */ new Map();
   errorHandler;
+  logger;
+  cooldowns;
+  defaultCooldown;
+  defaultGuards = [];
+  onUsage;
   /** Register one or more commands. Later registrations override by name. */
   add(...commands) {
     for (const command2 of commands) this.commands.set(command2.name, command2);
@@ -477,6 +2566,27 @@ var CommandRegistry = class {
     this.errorHandler = handler;
     return this;
   }
+  /** Attach a logger used for dispatch tracing (debug level). */
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  /** Wire a shared cooldown manager and an optional default cooldown for every command. */
+  setCooldowns(manager, defaultCooldown) {
+    this.cooldowns = manager;
+    this.defaultCooldown = defaultCooldown;
+    return this;
+  }
+  /** Guards that run before every command's own guards. */
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
+  /** Attach a hook called after each successful command execution. */
+  setUsageHook(hook) {
+    this.onUsage = hook;
+    return this;
+  }
   /** Serialise every command to discord REST payloads. */
   toJSON() {
     return this.all().map((c) => c.toJSON());
@@ -485,10 +2595,60 @@ var CommandRegistry = class {
   async handle(interaction) {
     const command2 = this.commands.get(interaction.commandName);
     if (command2 === void 0) return;
+    this.logger?.debug("command", {
+      data: { command: interaction.commandName, user: interaction.user.id }
+    });
+    const cooldown = command2.cooldown ?? this.defaultCooldown;
+    if (cooldown !== void 0 && this.cooldowns !== void 0) {
+      const result = this.cooldowns.consume(command2.name, cooldown, actorOf2(interaction));
+      if (!result.allowed) {
+        await this.replyCooldown(interaction, cooldown, result.remaining);
+        return;
+      }
+    }
+    const guards = combineGuards3(this.defaultGuards, command2.guards);
+    if (guards.length > 0) {
+      const guardResult = await runGuards(interaction, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("command denied", {
+          data: {
+            command: command2.name,
+            user: interaction.user.id,
+            reason: guardResult.reason ?? ""
+          }
+        });
+        await this.replyDenied(interaction, guardResult.reason);
+        return;
+      }
+    }
+    const start = Date.now();
     try {
       await command2.execute(interaction);
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        outcome: "success",
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
       if (this.errorHandler !== void 0) {
         await this.errorHandler(err, interaction);
       } else {
@@ -538,10 +2698,56 @@ var CommandRegistry = class {
     } catch {
     }
   }
+  async replyCooldown(interaction, config, remaining) {
+    this.logger?.debug("cooldown", {
+      data: { command: interaction.commandName, user: interaction.user.id, remaining }
+    });
+    const content = formatCooldownMessage(config, remaining);
+    try {
+      if (interaction.deferred) await interaction.editReply({ content });
+      else if (interaction.replied) await interaction.followUp({ content, flags: discord_js.MessageFlags.Ephemeral });
+      else await interaction.reply({ content, flags: discord_js.MessageFlags.Ephemeral });
+    } catch {
+    }
+  }
+  async replyDenied(interaction, reason) {
+    const embeds = clientEmbeds4(interaction.client);
+    const text = reason ?? "You don't have permission to use this.";
+    try {
+      const payload = { embeds: [embeds.error(text)], flags: discord_js.MessageFlags.Ephemeral };
+      if (interaction.deferred) await interaction.editReply({ embeds: payload.embeds });
+      else if (interaction.replied) await interaction.followUp(payload);
+      else await interaction.reply(payload);
+    } catch {
+    }
+  }
 };
+function combineGuards3(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function clientEmbeds4(client) {
+  const host = client;
+  return host.embeds ?? defaultEmbeds;
+}
+function actorOf2(interaction) {
+  const member = interaction.member;
+  let roleIds = [];
+  if (member !== null) {
+    const roles = member.roles;
+    roleIds = Array.isArray(roles) ? roles : [...roles.cache.keys()];
+  }
+  return {
+    userId: interaction.user.id,
+    roleIds,
+    guildId: interaction.guildId,
+    channelId: interaction.channelId
+  };
+}
 
 // src/events.ts
-function toError(value) {
+function toError2(value) {
   return value instanceof Error ? value : new Error(String(value));
 }
 function build(name, once, run) {
@@ -554,10 +2760,10 @@ function build(name, once, run) {
         try {
           const result = run(...args);
           if (result instanceof Promise) {
-            result.catch((error) => client.emit("error", toError(error)));
+            result.catch((error) => client.emit("error", toError2(error)));
           }
         } catch (error) {
-          client.emit("error", toError(error));
+          client.emit("error", toError2(error));
         }
       };
       listeners.set(client, listener);
@@ -763,7 +2969,7 @@ var ModalContext = class extends BaseContext {
     return this.interaction.customId;
   }
 };
-function toError2(value) {
+function toError3(value) {
   return value instanceof Error ? value : new Error(String(value));
 }
 var ComponentRegistry = class {
@@ -775,6 +2981,9 @@ var ComponentRegistry = class {
   mentionableSelects = /* @__PURE__ */ new Map();
   modals = /* @__PURE__ */ new Map();
   errorHandler;
+  logger;
+  onUsage;
+  defaultGuards = [];
   /** Register one or more components. Later registrations override by namespace. */
   add(...defs) {
     for (const def of defs) {
@@ -809,6 +3018,21 @@ var ComponentRegistry = class {
     this.errorHandler = handler;
     return this;
   }
+  /** Attach a logger used for dispatch tracing (debug level). */
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  /** Attach a hook called after each successful component handler run. */
+  setUsageHook(hook) {
+    this.onUsage = hook;
+    return this;
+  }
+  /** Guards that run before every component's own guards. */
+  setDefaultGuards(guards) {
+    this.defaultGuards = guards;
+    return this;
+  }
   /** Total number of registered components. */
   get size() {
     return this.buttons.size + this.stringSelects.size + this.userSelects.size + this.roleSelects.size + this.channelSelects.size + this.mentionableSelects.size + this.modals.size;
@@ -843,12 +3067,48 @@ var ComponentRegistry = class {
   }
   async exec(route, interaction) {
     if (route === void 0) return false;
+    this.logger?.debug("component", { data: { customId: interaction.customId } });
+    const guards = combineGuards4(this.defaultGuards, route.guards);
+    if (guards.length > 0) {
+      const guardResult = await runGuards(interaction, guards);
+      if (!guardResult.allowed) {
+        this.logger?.debug("component denied", {
+          data: { customId: interaction.customId, reason: guardResult.reason ?? "" }
+        });
+        await replyDeniedComponent(interaction, guardResult.reason);
+        return true;
+      }
+    }
     const { values } = parseCustomId(interaction.customId);
     const params = paramsFromValues(route.paramNames, values);
+    const start = Date.now();
     try {
       await route.handle(interaction, params);
+      this.onUsage?.({
+        type: "component",
+        name: route.namespace,
+        outcome: "success",
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
     } catch (error) {
-      const err = toError2(error);
+      const err = toError3(error);
+      this.onUsage?.({
+        type: "component",
+        name: route.namespace,
+        outcome: "error",
+        errorMessage: err.message,
+        durationMs: Date.now() - start,
+        userId: interaction.user.id,
+        userTag: interaction.user.tag,
+        guildId: interaction.guildId,
+        channelId: interaction.channelId,
+        timestamp: /* @__PURE__ */ new Date()
+      });
       if (this.errorHandler !== void 0) {
         await this.errorHandler(err, interaction);
       } else {
@@ -864,6 +3124,25 @@ var ComponentRegistry = class {
 function namespaceOf(customId) {
   return parseCustomId(customId).namespace;
 }
+function combineGuards4(defaults, own) {
+  if (own === void 0 || own.length === 0) return defaults;
+  if (defaults.length === 0) return own;
+  return [...defaults, ...own];
+}
+function clientEmbeds5(client) {
+  return client.embeds ?? defaultEmbeds;
+}
+async function replyDeniedComponent(interaction, reason) {
+  const embeds = clientEmbeds5(interaction.client);
+  const text = reason ?? "You don't have permission to use this.";
+  try {
+    const payload = { embeds: [embeds.error(text)], flags: discord_js.MessageFlags.Ephemeral };
+    if (interaction.deferred) await interaction.editReply({ embeds: payload.embeds });
+    else if (interaction.replied) await interaction.followUp(payload);
+    else await interaction.reply(payload);
+  } catch {
+  }
+}
 function resolveButtonStyle(input) {
   if (input === void 0) return discord_js.ButtonStyle.Secondary;
   return typeof input === "number" ? input : discord_js.ButtonStyle[input];
@@ -875,6 +3154,7 @@ function button(config) {
     kind: "button",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new ButtonContext(interaction, params));
     },
@@ -907,6 +3187,7 @@ function stringSelect(config) {
     kind: "stringSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new StringSelectContext(interaction, params));
     },
@@ -924,6 +3205,7 @@ function userSelect(config) {
     kind: "userSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new UserSelectContext(interaction, params));
     },
@@ -941,6 +3223,7 @@ function roleSelect(config) {
     kind: "roleSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new RoleSelectContext(interaction, params));
     },
@@ -958,6 +3241,7 @@ function channelSelect(config) {
     kind: "channelSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new ChannelSelectContext(interaction, params));
     },
@@ -976,6 +3260,7 @@ function mentionableSelect(config) {
     kind: "mentionableSelect",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       await config.run(new MentionableSelectContext(interaction, params));
     },
@@ -1018,6 +3303,7 @@ function modal(config) {
     kind: "modal",
     namespace: compiled.namespace,
     paramNames: compiled.paramNames,
+    guards: config.guards,
     async handle(interaction, params) {
       const fields = {};
       for (const key of fieldKeys) {
@@ -1057,6 +3343,9 @@ function isRegisterable(value) {
   if (typeof record["kind"] === "string" && typeof record["handle"] === "function") {
     return true;
   }
+  if ((record["kind"] === "task" || record["kind"] === "prefixCommand") && typeof record["run"] === "function") {
+    return true;
+  }
   return false;
 }
 async function collectModules(dir, options = {}) {
@@ -1111,15 +3400,64 @@ var SpearClient = class extends discord_js.Client {
   events = new EventRegistry();
   /** Button / select / modal registry and router. */
   components = new ComponentRegistry();
+  /** Structured logger shared across spearkit and available to your code. */
+  logger;
+  /** Shared cooldown manager used by command dispatch; also usable directly. */
+  cooldowns = new CooldownManager();
+  /** Cron/interval task scheduler; started on ready and stopped on destroy. */
+  scheduler = new TaskScheduler();
+  /** Prefix (text) command registry, dispatched from `messageCreate`. */
+  prefix = new PrefixRegistry();
+  /** Usage tracker: records who used what to a store and/or a Discord channel. */
+  usage = new UsageTracker();
+  /** Preset embed factory used by `ctx.error/success/info/warn` and available to your code. */
+  embeds;
+  /** User- and message-context-menu command registry. */
+  contextMenus = new ContextMenuRegistry();
+  envConfig;
   constructor(options = {}) {
-    const { intents, ...rest } = options;
+    const { intents, logger, dotenv, cooldown, prefix, usage, embeds, guards, ...rest } = options;
     super({ ...rest, intents: intents ?? Intents.default });
+    this.embeds = embeds instanceof Embeds ? embeds : new Embeds(embeds);
+    this.envConfig = dotenv === false ? false : dotenv === void 0 || dotenv === true ? {} : dotenv;
+    this.logger = logger instanceof Logger ? logger : new Logger(logger);
+    const defaultCooldown = cooldown !== void 0 ? normalizeCooldown(cooldown) : void 0;
+    this.commands.setLogger(this.logger.child("commands"));
+    this.commands.setCooldowns(this.cooldowns, defaultCooldown);
+    this.components.setLogger(this.logger.child("components"));
+    this.contextMenus.setLogger(this.logger.child("contextMenus"));
+    this.contextMenus.setCooldowns(this.cooldowns, defaultCooldown);
+    this.prefix.setLogger(this.logger.child("prefix"));
+    this.prefix.setCooldowns(this.cooldowns, defaultCooldown);
+    if (prefix !== void 0) this.prefix.setOptions(prefix);
+    this.scheduler.setLogger(this.logger.child("scheduler"));
+    if (guards !== void 0 && guards.length > 0) {
+      this.commands.setDefaultGuards(guards);
+      this.contextMenus.setDefaultGuards(guards);
+      this.components.setDefaultGuards(guards);
+      this.prefix.setDefaultGuards(guards);
+    }
+    this.usage.setClient(this).setLogger(this.logger.child("usage"));
+    if (usage !== void 0) {
+      if (usage.store !== void 0) this.usage.setStore(usage.store);
+      if (usage.channel !== void 0) this.usage.reportTo(usage.channel, usage.format);
+      const onUsage = (event2) => this.usage.track(event2);
+      this.commands.setUsageHook(onUsage);
+      this.contextMenus.setUsageHook(onUsage);
+      this.components.setUsageHook(onUsage);
+      this.prefix.setUsageHook(onUsage);
+    }
     this.events.attachAll(this);
     this.on("interactionCreate", (interaction) => this.route(interaction));
+    this.on("error", (error) => this.logger.error("client error", { error: toError(error) }));
+    this.once("clientReady", () => this.scheduler.start(this));
+    this.on("messageCreate", (message) => {
+      void this.prefix.handle(message);
+    });
   }
   /**
-   * Register commands, events and components in one call. Each item is routed
-   * to the matching registry based on its kind.
+   * Register commands, events, components, scheduled tasks, prefix commands
+   * and context menus in one call. Each item is routed to its matching registry.
    */
   register(...items) {
     for (const item of items) {
@@ -1127,6 +3465,14 @@ var SpearClient = class extends discord_js.Client {
         this.commands.add(item);
       } else if ("attach" in item) {
         this.events.add(item);
+      } else if (item.kind === "task") {
+        this.scheduler.add(item);
+      } else if (item.kind === "prefixCommand") {
+        this.prefix.add(item);
+      } else if (item.kind === "userMenu") {
+        this.contextMenus.add(item);
+      } else if (item.kind === "messageMenu") {
+        this.contextMenus.add(item);
       } else {
         this.components.add(item);
       }
@@ -1152,6 +3498,7 @@ var SpearClient = class extends discord_js.Client {
    * token is passed.
    */
   async start(token) {
+    if (this.envConfig !== false) loadEnv(this.envConfig);
     const resolved = token ?? process.env.DISCORD_TOKEN;
     if (resolved === void 0 || resolved.length === 0) {
       throw new Error("spearkit: start() needs a token (pass one or set DISCORD_TOKEN)");
@@ -1160,8 +3507,9 @@ var SpearClient = class extends discord_js.Client {
     return this;
   }
   /**
-   * Push the registered slash commands to discord using the client's own
-   * authenticated REST connection. Call after the client is ready.
+   * Push the registered slash commands to Discord using the client's REST
+   * connection. Slash-only — use {@link deployAllCommands} to include context
+   * menus in the same request.
    */
   async deployCommands(options = {}) {
     const applicationId = this.application?.id ?? this.user?.id;
@@ -1170,16 +3518,102 @@ var SpearClient = class extends discord_js.Client {
     }
     return this.commands.deploy({ rest: this.rest, applicationId, guildId: options.guildId });
   }
+  /**
+   * Deploy slash commands AND context menus together to Discord in a single
+   * PUT. Use this once you mix `userCommand` / `messageCommand` with `command`.
+   */
+  /**
+   * Deploy slash commands AND context menus together. Supports a `diff`
+   * strategy that fetches the remote set first and skips the PUT when
+   * nothing changed, and a `dryRun` flag that returns the body without
+   * touching Discord (perfect for CI deploy gates).
+   *
+   * @returns the API's DeployResult on PUT, or a skipped report when
+   * `dryRun: true` is set OR `strategy: "diff"` finds no changes.
+   */
+  async deployAllCommands(options = {}) {
+    const applicationId = options.applicationId ?? this.application?.id ?? this.user?.id;
+    if (applicationId == null) {
+      throw new Error("spearkit: deployAllCommands() must run after the client is ready");
+    }
+    const body = [...this.commands.toJSON(), ...this.contextMenus.toJSON()];
+    const route = options.guildId !== void 0 ? discord_js.Routes.applicationGuildCommands(applicationId, options.guildId) : discord_js.Routes.applicationCommands(applicationId);
+    if (options.dryRun === true) {
+      return { skipped: true, reason: "dry-run", body };
+    }
+    if (options.strategy === "diff") {
+      const remote = await this.rest.get(route);
+      if (commandsEqual(body, remote)) {
+        return { skipped: true, reason: "no-changes", body };
+      }
+    }
+    return await this.rest.put(route, { body });
+  }
+  /** Define and register a scheduled task in one call. */
+  schedule(config) {
+    const scheduled = task(config);
+    this.scheduler.add(scheduled);
+    return scheduled;
+  }
+  /** Stop the scheduler, then tear down the discord.js client. */
+  async destroy() {
+    this.scheduler.stop();
+    await super.destroy();
+  }
   async route(interaction) {
     if (interaction.isChatInputCommand()) {
       await this.commands.handle(interaction);
     } else if (interaction.isAutocomplete()) {
       await this.commands.handleAutocomplete(interaction);
+    } else if (interaction.isUserContextMenuCommand()) {
+      await this.contextMenus.handleUser(interaction);
+    } else if (interaction.isMessageContextMenuCommand()) {
+      await this.contextMenus.handleMessage(interaction);
     } else {
       await this.components.handle(interaction);
     }
   }
 };
+function commandsEqual(local, remote) {
+  if (local.length !== remote.length) return false;
+  const lset = new Set(local.map(commandHash));
+  for (const r of remote) {
+    if (!lset.has(commandHash(r))) return false;
+  }
+  return true;
+}
+function commandHash(cmd) {
+  const c = cmd;
+  return JSON.stringify({
+    name: c.name,
+    type: c.type ?? 1,
+    description: c.description ?? "",
+    nsfw: c.nsfw === true,
+    default_member_permissions: c.default_member_permissions ?? null,
+    contexts: Array.isArray(c.contexts) ? [...c.contexts].sort((a, b) => a - b) : null,
+    options: normaliseOptions(c.options)
+  });
+}
+function normaliseOptions(options) {
+  if (!Array.isArray(options)) return [];
+  return options.map((o) => {
+    const opt = o;
+    return {
+      name: opt.name,
+      type: opt.type,
+      description: opt.description ?? "",
+      required: opt.required === true,
+      choices: Array.isArray(opt.choices) ? [...opt.choices].map((ch) => ({ name: ch.name, value: ch.value })).sort((a, b) => String(a.name).localeCompare(String(b.name))) : null,
+      options: normaliseOptions(opt.options),
+      channel_types: Array.isArray(opt.channel_types) ? [...opt.channel_types].sort((a, b) => a - b) : null,
+      min_value: opt.min_value ?? null,
+      max_value: opt.max_value ?? null,
+      min_length: opt.min_length ?? null,
+      max_length: opt.max_length ?? null,
+      autocomplete: opt.autocomplete === true
+    };
+  }).sort((a, b) => String(a.name).localeCompare(String(b.name)));
+}
 
 // src/plugin.ts
 function definePlugin(plugin) {
@@ -1193,45 +3627,112 @@ exports.ChannelSelectContext = ChannelSelectContext;
 exports.CommandContext = CommandContext;
 exports.CommandRegistry = CommandRegistry;
 exports.ComponentRegistry = ComponentRegistry;
+exports.ContextMenuRegistry = ContextMenuRegistry;
+exports.CooldownManager = CooldownManager;
+exports.CronExpression = CronExpression;
+exports.DEFAULT_EMBED_COLORS = DEFAULT_EMBED_COLORS;
+exports.DEFAULT_EMBED_ICONS = DEFAULT_EMBED_ICONS;
+exports.Embeds = Embeds;
 exports.EventRegistry = EventRegistry;
 exports.Intents = Intents;
+exports.JsonFileUsageStore = JsonFileUsageStore;
+exports.KeyedLock = KeyedLock;
+exports.Logger = Logger;
 exports.MAX_CUSTOM_ID_LENGTH = MAX_CUSTOM_ID_LENGTH;
+exports.MemoryCache = MemoryCache;
+exports.MemoryUsageStore = MemoryUsageStore;
 exports.MentionableSelectContext = MentionableSelectContext;
 exports.MessageComponentContext = MessageComponentContext;
+exports.MessageContextMenuContext = MessageContextMenuContext;
 exports.ModalContext = ModalContext;
+exports.PrefixArgsBuilder = PrefixArgsBuilder;
+exports.PrefixContext = PrefixContext;
+exports.PrefixRegistry = PrefixRegistry;
 exports.RoleSelectContext = RoleSelectContext;
 exports.SlashCommand = SlashCommand;
 exports.SpearClient = SpearClient;
 exports.StringSelectContext = StringSelectContext;
+exports.TaskScheduler = TaskScheduler;
+exports.UsageTracker = UsageTracker;
+exports.UserContextMenuContext = UserContextMenuContext;
 exports.UserSelectContext = UserSelectContext;
 exports.asEphemeral = asEphemeral;
 exports.buildCustomId = buildCustomId;
+exports.buildPaginatorPage = buildPaginatorPage;
 exports.button = button;
 exports.channelSelect = channelSelect;
 exports.collectModules = collectModules;
 exports.command = command;
 exports.commandGroup = commandGroup;
 exports.compilePattern = compilePattern;
+exports.confirm = confirm;
+exports.consoleSink = consoleSink;
+exports.createCache = createCache;
+exports.cron = cron;
+exports.defaultEmbeds = defaultEmbeds;
 exports.definePlugin = definePlugin;
+exports.denied = denied;
+exports.discordTimestamp = discordTimestamp;
+exports.dmOnly = dmOnly;
+exports.effectiveDuration = effectiveDuration;
+exports.env = env;
 exports.event = event;
+exports.fetchChannel = fetchChannel;
+exports.fetchGuild = fetchGuild;
+exports.fetchMember = fetchMember;
+exports.fetchMessage = fetchMessage;
+exports.fetchRole = fetchRole;
+exports.fetchUser = fetchUser;
+exports.formatCooldownMessage = formatCooldownMessage;
+exports.formatDuration = formatDuration;
+exports.formatUsage = formatUsage;
+exports.guard = guard;
+exports.guildOnly = guildOnly;
+exports.jsonlSink = jsonlSink;
 exports.linkButton = linkButton;
+exports.loadConfig = loadConfig;
+exports.loadConfigAsync = loadConfigAsync;
+exports.loadEnv = loadEnv;
 exports.loadInto = loadInto;
+exports.lookup = lookup;
+exports.lookupOptional = lookupOptional;
 exports.mentionableSelect = mentionableSelect;
+exports.messageCommand = messageCommand;
 exports.modal = modal;
+exports.normalizeCooldown = normalizeCooldown;
 exports.normalizeReply = normalizeReply;
 exports.option = option;
 exports.optionsHaveAutocomplete = optionsHaveAutocomplete;
+exports.paginate = paginate;
 exports.paramsFromValues = paramsFromValues;
 exports.parseCustomId = parseCustomId;
+exports.parseDuration = parseDuration;
+exports.parseEnv = parseEnv;
+exports.prefixArgs = prefixArgs;
+exports.prefixCommand = prefixCommand;
 exports.readOption = readOption;
+exports.relativeTimestamp = relativeTimestamp;
+exports.requireAllRoles = requireAllRoles;
+exports.requireAnyRole = requireAnyRole;
+exports.requireBotPermissions = requireBotPermissions;
+exports.requireOwner = requireOwner;
+exports.requireUserPermissions = requireUserPermissions;
 exports.roleSelect = roleSelect;
 exports.row = row;
+exports.runGuards = runGuards;
+exports.safeFetch = safeFetch;
+exports.safeTry = safeTry;
 exports.stringSelect = stringSelect;
 exports.subcommand = subcommand;
 exports.subcommandGroup = subcommandGroup;
+exports.task = task;
 exports.textInput = textInput;
 exports.toAPIOption = toAPIOption;
+exports.toError = toError;
+exports.userCommand = userCommand;
 exports.userSelect = userSelect;
+exports.webhookSink = webhookSink;
+exports.withSafeTimeout = withSafeTimeout;
 Object.keys(discord_js).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
     enumerable: true,