spearkit 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -1,11 +1,805 @@
 'use strict';
 
 var discord_js = require('discord.js');
-var promises = require('fs/promises');
+var fs = require('fs');
 var path = require('path');
+var promises = require('fs/promises');
 var url = require('url');
 
 // src/index.ts
+
+// src/logger.ts
+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));
+}
+var Logger = class _Logger {
+  state;
+  /** The scope prefix applied to every entry, if any. */
+  scope;
+  constructor(options = {}) {
+    this.state = {
+      threshold: options.level ?? "info",
+      sink: options.sink ?? consoleSink
+    };
+    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;
+  }
+  /** 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;
+    this.state.sink({
+      level,
+      message,
+      scope: this.scope,
+      timestamp: /* @__PURE__ */ new Date(),
+      error: options?.error,
+      data: options?.data
+    });
+  }
+  /** 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/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/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 guard = 0; guard < 1e5; guard++) {
+      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;
+  /** 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);
+  }
+  /** 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);
+  }
+  /** 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) {
+  return {
+    kind: "prefixCommand",
+    name: config.name,
+    aliases: config.aliases ?? [],
+    description: config.description,
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0,
+    run: async (ctx) => {
+      await config.run(ctx);
+    }
+  };
+}
+var PrefixContext = class {
+  constructor(message, commandName, args, rest) {
+    this.message = message;
+    this.commandName = commandName;
+    this.args = args;
+    this.rest = rest;
+  }
+  message;
+  commandName;
+  args;
+  rest;
+  get client() {
+    return this.message.client;
+  }
+  get author() {
+    return this.message.author;
+  }
+  get member() {
+    return this.message.member;
+  }
+  get guild() {
+    return this.message.guild;
+  }
+  get guildId() {
+    return this.message.guildId;
+  }
+  get channel() {
+    return this.message.channel;
+  }
+  get channelId() {
+    return this.message.channelId;
+  }
+  /** Reply to the triggering message. */
+  reply(content) {
+    return this.message.reply(content);
+  }
+  /** 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;
+  }
+};
+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 };
+  }
+  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;
+  onUsage;
+  /** Configure prefixes and matching behaviour. */
+  setOptions(input) {
+    this.options = resolveOptions(input);
+    return this;
+  }
+  /** Attach a logger for dispatch tracing and error reporting. */
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  /** Attach a hook called after each successful prefix command run. */
+  setUsageHook(hook) {
+    this.onUsage = hook;
+    return this;
+  }
+  /** Share a cooldown manager and an optional default cooldown. */
+  setCooldowns(manager, defaultCooldown) {
+    this.cooldowns = manager;
+    this.defaultCooldown = defaultCooldown;
+    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;
+  }
+  /**
+   * 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 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 args = rest.length > 0 ? rest.split(/\s+/) : [];
+    try {
+      await command2.run(new PrefixContext(message, name, args, rest));
+      this.onUsage?.({
+        type: "prefix",
+        name: command2.name,
+        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 });
+      if (this.errorHandler !== void 0) await this.errorHandler(err, message);
+    }
+    return true;
+  }
+};
+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;
+  }
+  /** 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 withEphemeralFlag(flags) {
   if (flags == null) return discord_js.MessageFlags.Ephemeral;
   if (typeof flags === "number" || typeof flags === "bigint") {
@@ -286,6 +1080,8 @@ var SlashCommand = class {
   json;
   executor;
   autocompleter;
+  /** Resolved cooldown configuration for this command, if any. */
+  cooldown;
   /** @internal */
   constructor(spec) {
     this.name = spec.name;
@@ -293,6 +1089,7 @@ var SlashCommand = class {
     this.json = spec.json;
     this.executor = spec.executor;
     this.autocompleter = spec.autocompleter;
+    this.cooldown = spec.cooldown;
   }
   /** Serialise to the discord REST chat-input command payload. */
   toJSON() {
@@ -307,7 +1104,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);
@@ -362,7 +1159,7 @@ 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({
@@ -370,14 +1167,15 @@ function command(config) {
     json: baseJSON(config, leafOptionsJSON(options)),
     hasAutocomplete: optionsHaveAutocomplete(options),
     executor,
-    autocompleter: makeAutocompleter(options)
+    autocompleter: makeAutocompleter(options),
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0
   });
 }
 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 {
@@ -441,12 +1239,17 @@ function commandGroup(config) {
     json: baseJSON(config, options),
     hasAutocomplete,
     executor,
-    autocompleter
+    autocompleter,
+    cooldown: config.cooldown !== void 0 ? normalizeCooldown(config.cooldown) : void 0
   });
 }
 var CommandRegistry = class {
   commands = /* @__PURE__ */ new Map();
   errorHandler;
+  logger;
+  cooldowns;
+  defaultCooldown;
+  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 +1280,22 @@ 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;
+  }
+  /** 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,8 +1304,28 @@ 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, actorOf(interaction));
+      if (!result.allowed) {
+        await this.replyCooldown(interaction, cooldown, result.remaining);
+        return;
+      }
+    }
     try {
       await command2.execute(interaction);
+      this.onUsage?.({
+        type: "command",
+        name: command2.name,
+        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));
       if (this.errorHandler !== void 0) {
@@ -538,10 +1377,36 @@ 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 {
+    }
+  }
 };
+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
+  };
+}
 
 // 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 +1419,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 +1628,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 +1640,8 @@ var ComponentRegistry = class {
   mentionableSelects = /* @__PURE__ */ new Map();
   modals = /* @__PURE__ */ new Map();
   errorHandler;
+  logger;
+  onUsage;
   /** Register one or more components. Later registrations override by namespace. */
   add(...defs) {
     for (const def of defs) {
@@ -809,6 +1676,16 @@ 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;
+  }
   /** 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 +1720,22 @@ var ComponentRegistry = class {
   }
   async exec(route, interaction) {
     if (route === void 0) return false;
+    this.logger?.debug("component", { data: { customId: interaction.customId } });
     const { values } = parseCustomId(interaction.customId);
     const params = paramsFromValues(route.paramNames, values);
     try {
       await route.handle(interaction, params);
+      this.onUsage?.({
+        type: "component",
+        name: route.namespace,
+        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);
       if (this.errorHandler !== void 0) {
         await this.errorHandler(err, interaction);
       } else {
@@ -1057,6 +1944,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,11 +2001,46 @@ 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();
+  envConfig;
   constructor(options = {}) {
-    const { intents, ...rest } = options;
+    const { intents, logger, dotenv, cooldown, prefix, usage, ...rest } = options;
     super({ ...rest, intents: intents ?? Intents.default });
+    this.envConfig = dotenv === false ? false : dotenv === void 0 || dotenv === true ? {} : dotenv;
+    this.logger = logger instanceof Logger ? logger : new Logger(logger);
+    this.commands.setLogger(this.logger.child("commands"));
+    const defaultCooldown = cooldown !== void 0 ? normalizeCooldown(cooldown) : void 0;
+    this.commands.setCooldowns(this.cooldowns, defaultCooldown);
+    this.components.setLogger(this.logger.child("components"));
     this.events.attachAll(this);
     this.on("interactionCreate", (interaction) => this.route(interaction));
+    this.on("error", (error) => this.logger.error("client error", { error: toError(error) }));
+    this.scheduler.setLogger(this.logger.child("scheduler"));
+    this.once("clientReady", () => this.scheduler.start(this));
+    this.prefix.setLogger(this.logger.child("prefix"));
+    this.prefix.setCooldowns(this.cooldowns, defaultCooldown);
+    if (prefix !== void 0) this.prefix.setOptions(prefix);
+    this.on("messageCreate", (message) => {
+      void this.prefix.handle(message);
+    });
+    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.components.setUsageHook(onUsage);
+      this.prefix.setUsageHook(onUsage);
+    }
   }
   /**
    * Register commands, events and components in one call. Each item is routed
@@ -1127,6 +2052,10 @@ 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 {
         this.components.add(item);
       }
@@ -1152,6 +2081,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)");
@@ -1179,6 +2109,17 @@ var SpearClient = class extends discord_js.Client {
       await this.components.handle(interaction);
     }
   }
+  /** 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();
+  }
 };
 
 // src/plugin.ts
@@ -1193,16 +2134,25 @@ exports.ChannelSelectContext = ChannelSelectContext;
 exports.CommandContext = CommandContext;
 exports.CommandRegistry = CommandRegistry;
 exports.ComponentRegistry = ComponentRegistry;
+exports.CooldownManager = CooldownManager;
+exports.CronExpression = CronExpression;
 exports.EventRegistry = EventRegistry;
 exports.Intents = Intents;
+exports.JsonFileUsageStore = JsonFileUsageStore;
+exports.Logger = Logger;
 exports.MAX_CUSTOM_ID_LENGTH = MAX_CUSTOM_ID_LENGTH;
+exports.MemoryUsageStore = MemoryUsageStore;
 exports.MentionableSelectContext = MentionableSelectContext;
 exports.MessageComponentContext = MessageComponentContext;
 exports.ModalContext = ModalContext;
+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.UserSelectContext = UserSelectContext;
 exports.asEphemeral = asEphemeral;
 exports.buildCustomId = buildCustomId;
@@ -1212,25 +2162,37 @@ exports.collectModules = collectModules;
 exports.command = command;
 exports.commandGroup = commandGroup;
 exports.compilePattern = compilePattern;
+exports.consoleSink = consoleSink;
+exports.cron = cron;
 exports.definePlugin = definePlugin;
+exports.effectiveDuration = effectiveDuration;
+exports.env = env;
 exports.event = event;
+exports.formatCooldownMessage = formatCooldownMessage;
+exports.formatUsage = formatUsage;
 exports.linkButton = linkButton;
+exports.loadEnv = loadEnv;
 exports.loadInto = loadInto;
 exports.mentionableSelect = mentionableSelect;
 exports.modal = modal;
+exports.normalizeCooldown = normalizeCooldown;
 exports.normalizeReply = normalizeReply;
 exports.option = option;
 exports.optionsHaveAutocomplete = optionsHaveAutocomplete;
 exports.paramsFromValues = paramsFromValues;
 exports.parseCustomId = parseCustomId;
+exports.parseEnv = parseEnv;
+exports.prefixCommand = prefixCommand;
 exports.readOption = readOption;
 exports.roleSelect = roleSelect;
 exports.row = row;
 exports.stringSelect = stringSelect;
 exports.subcommand = subcommand;
 exports.subcommandGroup = subcommandGroup;
+exports.task = task;
 exports.textInput = textInput;
 exports.toAPIOption = toAPIOption;
+exports.toError = toError;
 exports.userSelect = userSelect;
 Object.keys(discord_js).forEach(function (k) {
   if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {