cordsmith 0.1.0

package/src/handler/context/functions/loadContextMenus.ts

@@ -0,0 +1,59 @@
+import { pathToFileURL } from "node:url";
+import { Collection } from "discord.js";
+import { logger } from "../../../utils";
+import type { ContextMenuCommand } from "../../@types/contextMenu";
+import { discoverModuleFiles } from "../../utils/files";
+
+export type LoadedContextMenus = Collection<string, ContextMenuCommand>;
+
+function isContextMenuModule(mod: unknown): mod is ContextMenuCommand {
+	if (!mod || typeof mod !== "object") return false;
+
+	const m = mod as Partial<ContextMenuCommand>;
+
+	return (
+		typeof m.execute === "function" &&
+		typeof m.data === "object" &&
+		typeof m.data?.toJSON === "function" &&
+		typeof (m.data as { name?: unknown }).name === "string" &&
+		((m.data as { name?: unknown }).name as string).length > 0 &&
+		(m.type === "user" || m.type === "message")
+	);
+}
+
+export async function loadContextMenusFromDisk(options: {
+	contextMenusDir: string;
+	extensions: string[];
+}): Promise<LoadedContextMenus> {
+	const { rootDir, files } = await discoverModuleFiles({
+		dir: options.contextMenusDir,
+		extensions: options.extensions,
+	});
+	const commands = new Collection<string, ContextMenuCommand>();
+	let loaded = 0;
+
+	for (const filePath of files) {
+		const fileUrl = pathToFileURL(filePath).href;
+		const imported = await import(fileUrl);
+		const cmd = imported.default;
+
+		if (!isContextMenuModule(cmd)) {
+			logger.warn(`Skipping invalid context menu module: ${filePath}`);
+			continue;
+		}
+
+		const name = cmd.data.name;
+
+		if (commands.has(name)) {
+			throw new Error(
+				`Duplicate context menu name "${name}" detected: ${filePath}`,
+			);
+		}
+
+		commands.set(name, cmd);
+		loaded += 1;
+	}
+
+	logger.info(`Loaded ${loaded} context menu command(s) from ${rootDir}`);
+	return commands;
+}

package/src/handler/context/functions/runContextMenuPreconditions.ts

@@ -0,0 +1,114 @@
+import type {
+	MessageContextMenuCommandInteraction,
+	UserContextMenuCommandInteraction,
+} from "discord.js";
+import type { ClientClass } from "../../../structure/Client";
+import type { ContextMenuMeta } from "../../@types/contextMenu";
+import type {
+	Precondition,
+	PreconditionResult,
+} from "../../@types/precondition";
+import type { CooldownStore } from "../../command/functions/cooldowns";
+import { BotPermissions } from "../../command/functions/preconditions/BotPermissions";
+import { Cooldown } from "../../command/functions/preconditions/Cooldown";
+import { GuildOnly } from "../../command/functions/preconditions/GuildOnly";
+import { OwnerOnly } from "../../command/functions/preconditions/OwnerOnly";
+import { UserPermissions } from "../../command/functions/preconditions/UserPermissions";
+
+export type ContextMenuPreconditionContext = {
+	interaction:
+		| UserContextMenuCommandInteraction
+		| MessageContextMenuCommandInteraction;
+	client: ClientClass;
+	meta: ContextMenuMeta;
+	ownerIds: Set<string>;
+	cooldowns: CooldownStore;
+};
+
+export type ContextMenuPreconditionFailure = {
+	message: string;
+	ephemeral: boolean;
+};
+
+export type RunContextMenuPreconditionsResult =
+	| { ok: true }
+	| { ok: false; failure: ContextMenuPreconditionFailure };
+
+/**
+ * Built-in preconditions run for every context menu invocation.
+ * Reuses the exact same objects as the slash command path so any fix
+ * in a built-in applies automatically to both interaction types.
+ */
+const BUILT_INS: Precondition[] = [
+	OwnerOnly,
+	GuildOnly,
+	Cooldown,
+	UserPermissions,
+	BotPermissions,
+];
+
+/**
+ * Runs built-in guards and any custom preconditions for a context menu invocation.
+ *
+ * Previously this file reimplemented all built-in logic inline, meaning a bug
+ * fix in e.g. Cooldown.ts would not apply here. Now it delegates to the shared
+ * precondition objects directly.
+ */
+export async function runContextMenuPreconditions(options: {
+	ctx: ContextMenuPreconditionContext;
+	registry: Map<string, Precondition>;
+}): Promise<RunContextMenuPreconditionsResult> {
+	const { ctx, registry } = options;
+
+	// Run built-ins first, in the same order as the slash command path
+	for (const precondition of BUILT_INS) {
+		const result: PreconditionResult = await precondition.run({
+			interaction: ctx.interaction as never,
+			client: ctx.client,
+			meta: ctx.meta as never,
+			ownerIds: ctx.ownerIds,
+			cooldowns: ctx.cooldowns,
+		});
+
+		if (!result.ok) {
+			return {
+				ok: false,
+				failure: {
+					message: result.message,
+					ephemeral: result.ephemeral ?? true,
+				},
+			};
+		}
+	}
+
+	// Run custom preconditions declared on this context menu command
+	for (const name of ctx.meta.preconditions ?? []) {
+		const precondition = registry.get(name);
+
+		if (!precondition) {
+			throw new Error(
+				`Precondition "${name}" is referenced by context menu "${ctx.interaction.commandName}" but was never registered.`,
+			);
+		}
+
+		const result: PreconditionResult = await precondition.run({
+			interaction: ctx.interaction as never,
+			client: ctx.client,
+			meta: ctx.meta as never,
+			ownerIds: ctx.ownerIds,
+			cooldowns: ctx.cooldowns,
+		});
+
+		if (!result.ok) {
+			return {
+				ok: false,
+				failure: {
+					message: result.message,
+					ephemeral: result.ephemeral ?? true,
+				},
+			};
+		}
+	}
+
+	return { ok: true };
+}

package/src/handler/context/index.ts

@@ -0,0 +1,12 @@
+export type {
+	ContextMenuCommand,
+	ContextMenuMeta,
+	MessageContextMenuCommand,
+	UserContextMenuCommand,
+} from "../@types/contextMenu";
+export {
+	defineMessageContextMenu,
+	defineUserContextMenu,
+} from "../@types/contextMenu";
+export type { ContextMenuHandlerOptions } from "./ContextMenuHandler";
+export { ContextMenuHandler } from "./ContextMenuHandler";

package/src/handler/events/EventHandler.ts

@@ -0,0 +1,45 @@
+import type { ClientClass } from "../../structure/Client";
+import type { AttachedHandler } from "./functions/attachEvents";
+import { attachEvents } from "./functions/attachEvents";
+import { type LoadedEvents, loadEventsFromDisk } from "./functions/loadEvents";
+
+export type EventHandlerOptions = {
+	client: ClientClass;
+	eventsDir: string;
+	extensions?: string[];
+};
+
+export class EventHandler {
+	private readonly client: ClientClass;
+	private readonly eventsDir: string;
+	private readonly extensions: string[];
+
+	public events: LoadedEvents = new Map();
+	public attachedHandlers: AttachedHandler[] = [];
+
+	private initialized = false;
+
+	constructor(options: EventHandlerOptions) {
+		this.client = options.client;
+		this.eventsDir = options.eventsDir;
+		this.extensions = options.extensions ?? [".ts"];
+	}
+
+	public async init(): Promise<void> {
+		if (this.initialized) {
+			throw new Error("EventHandler.init() was called more than once.");
+		}
+		this.initialized = true;
+
+		this.events = await loadEventsFromDisk({
+			eventsDir: this.eventsDir,
+			extensions: this.extensions,
+		});
+
+		// Store the return value so callers can detach listeners later via detachEvents()
+		this.attachedHandlers = attachEvents({
+			client: this.client,
+			events: this.events,
+		});
+	}
+}

package/src/handler/events/functions/attachEvents.ts

@@ -0,0 +1,95 @@
+import { type ClientEvents, Events } from "discord.js";
+import type { ClientClass } from "../../../structure/Client";
+import { logger } from "../../../utils";
+import type { LoadedEvents, LoadedListener } from "./loadEvents";
+
+export type AttachedHandler = {
+	eventName: keyof ClientEvents;
+	once: boolean;
+	fn: (...args: unknown[]) => void;
+};
+
+const KNOWN_EVENT_NAMES = new Set<string>(Object.values(Events));
+
+async function runListeners<K extends keyof ClientEvents>(options: {
+	client: ClientClass;
+	eventName: K;
+	listeners: LoadedListener[];
+	args: ClientEvents[K];
+}): Promise<void> {
+	const { client, eventName, listeners, args } = options;
+
+	for (const listener of listeners) {
+		try {
+			await listener.execute({ client, args });
+		} catch (err) {
+			logger.error(
+				`Error in event "${String(eventName)}" listener (${listener.filePath})`,
+				err,
+			);
+		}
+	}
+}
+
+export function attachEvents(options: {
+	client: ClientClass;
+	events: LoadedEvents;
+}): AttachedHandler[] {
+	const { client, events } = options;
+
+	const attached: AttachedHandler[] = [];
+
+	for (const [eventName, listeners] of events) {
+		if (!KNOWN_EVENT_NAMES.has(String(eventName))) {
+			logger.warn(
+				`Unknown event folder "${String(
+					eventName,
+				)}". Check spelling/casing. Files inside will still be attached, but may never fire.`,
+			);
+		}
+
+		const onceListeners = listeners.filter((l) => l.once);
+		const onListeners = listeners.filter((l) => !l.once);
+
+		if (onListeners.length > 0) {
+			const fn = (...args: unknown[]) => {
+				void runListeners({
+					client,
+					eventName: eventName as never,
+					listeners: onListeners,
+					args: args as never,
+				});
+			};
+
+			client.on(eventName, fn as never);
+			attached.push({ eventName, once: false, fn });
+		}
+
+		if (onceListeners.length > 0) {
+			const fn = (...args: unknown[]) => {
+				void runListeners({
+					client,
+					eventName: eventName as never,
+					listeners: onceListeners,
+					args: args as never,
+				});
+			};
+
+			client.once(eventName, fn as never);
+			attached.push({ eventName, once: true, fn });
+		}
+	}
+
+	return attached;
+}
+
+export function detachEvents(options: {
+	client: ClientClass;
+	attached: AttachedHandler[];
+}): void {
+	const { client, attached } = options;
+
+	for (const h of attached) {
+		client.off(h.eventName, h.fn as never);
+	}
+}

package/src/handler/events/functions/loadEvents.ts

@@ -0,0 +1,93 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { logger } from "../../../utils";
+import type { EventListenerModule, EventName } from "../../@types/event";
+import { discoverModuleFiles } from "../../utils/files";
+
+export type LoadedListener = {
+	filePath: string;
+	once: boolean;
+	order: number;
+	execute: EventListenerModule["execute"];
+};
+
+export type LoadedEvents = Map<EventName, LoadedListener[]>;
+
+function isListenerModule(mod: unknown): mod is EventListenerModule {
+	if (!mod || typeof mod !== "object") return false;
+	const m = mod as Partial<EventListenerModule>;
+	return typeof m.execute === "function";
+}
+
+/**
+ * Derive the event name from the file path.
+ *
+ * Normalises path separators before splitting so behaviour is consistent on
+ * both POSIX and Windows (where path.sep would be "\\").
+ *
+ * Expected structure: <eventsDir>/<eventName>/[...].ts
+ */
+function getEventNameFromFilePath(
+	eventsDirAbs: string,
+	filePath: string,
+): string | null {
+	const rel = path.relative(eventsDirAbs, filePath).replace(/\\/g, "/"); // normalise Windows backslashes
+
+	const parts = rel.split("/").filter(Boolean);
+	return parts[0] ?? null;
+}
+
+export async function loadEventsFromDisk(options: {
+	eventsDir: string;
+	extensions: string[];
+}): Promise<LoadedEvents> {
+	const { rootDir, files } = await discoverModuleFiles({
+		dir: options.eventsDir,
+		extensions: options.extensions,
+	});
+	const events: LoadedEvents = new Map();
+	let loaded = 0;
+
+	for (const filePath of files) {
+		const eventNameRaw = getEventNameFromFilePath(rootDir, filePath);
+		if (!eventNameRaw) continue;
+
+		const fileUrl = pathToFileURL(filePath).href;
+		const imported = await import(fileUrl);
+		const mod = imported.default;
+
+		if (!isListenerModule(mod)) {
+			logger.warn(`Skipping invalid event listener module: ${filePath}`);
+			continue;
+		}
+
+		if (mod.enabled === false) continue;
+
+		const eventName = eventNameRaw as EventName;
+
+		const listener: LoadedListener = {
+			filePath,
+			once: mod.once ?? false,
+			order: mod.order ?? 0,
+			execute: mod.execute,
+		};
+
+		const arr = events.get(eventName) ?? [];
+		arr.push(listener);
+		events.set(eventName, arr);
+
+		loaded += 1;
+	}
+
+	for (const [eventName, listeners] of events) {
+		listeners.sort((a, b) => {
+			if (a.order !== b.order) return a.order - b.order;
+			return a.filePath.localeCompare(b.filePath);
+		});
+		events.set(eventName, listeners);
+	}
+
+	logger.info(`Loaded ${loaded} event listener file(s) from ${rootDir}`);
+
+	return events;
+}

package/src/handler/events/index.ts

@@ -0,0 +1,2 @@
+export type { EventHandlerOptions } from "./EventHandler";
+export { EventHandler } from "./EventHandler";

package/src/handler/manager/HandlerManager.ts

@@ -0,0 +1,225 @@
+import type { ClientClass } from "../../structure/Client";
+import { logger } from "../../utils";
+import type { Precondition } from "../@types/precondition";
+import {
+	CommandHandler,
+	type CommandHandlerOptions,
+} from "../command/CommandHandler";
+import {
+	ContextMenuHandler,
+	type ContextMenuHandlerOptions,
+} from "../context/ContextMenuHandler";
+import { EventHandler, type EventHandlerOptions } from "../events/EventHandler";
+import { detachEvents } from "../events/functions/attachEvents";
+import { TaskHandler, type TaskHandlerOptions } from "../tasks/TaskHandler";
+import { registerCommands } from "../command/functions/registerCommands";
+import {
+	combineRegistrationPlans,
+	type HandlerRegistrationPlan,
+} from "./registrationPlans";
+
+// Options for each handler are the same as their standalone versions,
+// minus `client` which is provided once at the top level.
+type WithoutClient<T> = Omit<T, "client">;
+
+export type HandlerManagerOptions = {
+	client: ClientClass;
+
+	commands?: WithoutClient<CommandHandlerOptions>;
+	contextMenus?: WithoutClient<ContextMenuHandlerOptions>;
+	events?: WithoutClient<EventHandlerOptions>;
+	tasks?: WithoutClient<TaskHandlerOptions>;
+
+	/**
+	 * If true (default), registers SIGINT and SIGTERM handlers for graceful
+	 * shutdown. Set to false if you manage process signals yourself.
+	 */
+	handleShutdownSignals?: boolean;
+};
+
+export class HandlerManager {
+	private readonly client: ClientClass;
+	private readonly commandsConfig?: WithoutClient<CommandHandlerOptions>;
+	private readonly contextMenusConfig?: WithoutClient<ContextMenuHandlerOptions>;
+	private readonly eventsConfig?: WithoutClient<EventHandlerOptions>;
+	private readonly tasksConfig?: WithoutClient<TaskHandlerOptions>;
+	private readonly shutdownSignals: boolean;
+
+	/**
+	 * Shared precondition registry passed to both CommandHandler and
+	 * ContextMenuHandler. Register preconditions here once and they are
+	 * available to both slash commands and context menus.
+	 */
+	public readonly preconditions = new Map<string, Precondition>();
+
+	public commandHandler?: CommandHandler;
+	public contextMenuHandler?: ContextMenuHandler;
+	public eventHandler?: EventHandler;
+	public taskHandler?: TaskHandler;
+
+	private initialized = false;
+
+	constructor(options: HandlerManagerOptions) {
+		this.client = options.client;
+		this.commandsConfig = options.commands;
+		this.contextMenusConfig = options.contextMenus;
+		this.eventsConfig = options.events;
+		this.tasksConfig = options.tasks;
+		this.shutdownSignals = options.handleShutdownSignals !== false;
+	}
+
+	/**
+	 * Register a custom precondition. Must be called before `init()`.
+	 * Available to both slash commands and context menus automatically.
+	 * Returns `this` for chaining.
+	 */
+	public registerPrecondition(precondition: Precondition): this {
+		if (this.initialized) {
+			throw new Error(
+				`Cannot register precondition "${precondition.name}" after init() has been called.`,
+			);
+		}
+
+		if (this.preconditions.has(precondition.name)) {
+			throw new Error(
+				`Precondition "${precondition.name}" is already registered.`,
+			);
+		}
+
+		this.preconditions.set(precondition.name, precondition);
+		return this;
+	}
+
+	/**
+	 * Initialises all configured handlers in the correct order:
+	 * 1. Events   — attach listeners first so nothing is missed
+	 * 2. Commands — load slash commands and attach interaction routing
+	 * 3. Context menus — load context menus and attach interaction routing
+	 * 4. Registration — register all application commands in one payload per scope
+	 * 5. Tasks    — start scheduled jobs last (bot should be ready)
+	 */
+	public async init(): Promise<void> {
+		if (this.initialized) {
+			throw new Error("HandlerManager.init() was called more than once.");
+		}
+		this.initialized = true;
+
+		const { client } = this;
+
+		logger.info("HandlerManager initialising...");
+		const startedAt = Date.now();
+
+		// 1. Events
+		if (this.eventsConfig) {
+			this.eventHandler = new EventHandler({
+				...this.eventsConfig,
+				client,
+			});
+			await this.eventHandler.init();
+		}
+
+		// 2. Commands
+		if (this.commandsConfig) {
+			this.commandHandler = new CommandHandler({
+				...this.commandsConfig,
+				client,
+				register: undefined,
+				preconditionRegistry: this.preconditions,
+			});
+			await this.commandHandler.init();
+		}
+
+		// 3. Context menus
+		if (this.contextMenusConfig) {
+			this.contextMenuHandler = new ContextMenuHandler({
+				...this.contextMenusConfig,
+				client,
+				register: undefined,
+				preconditionRegistry: this.preconditions,
+			});
+			await this.contextMenuHandler.init();
+		}
+
+		await this.registerApplicationCommands();
+
+		// 4. Tasks
+		if (this.tasksConfig) {
+			this.taskHandler = new TaskHandler({
+				...this.tasksConfig,
+				client,
+			});
+			await this.taskHandler.init();
+		}
+
+		logger.info(`HandlerManager ready in ${Date.now() - startedAt}ms.`);
+
+		if (this.shutdownSignals) {
+			this.registerShutdownSignals();
+		}
+	}
+
+	/**
+	 * Gracefully tears down all handlers:
+	 * - Cancels all scheduled tasks
+	 * - Detaches all event listeners
+	 *
+	 * Safe to call multiple times.
+	 */
+	public shutdown(): void {
+		logger.info("HandlerManager shutting down...");
+
+		this.taskHandler?.cancelAll();
+		this.commandHandler?.detach();
+		this.contextMenuHandler?.detach();
+
+		if (this.eventHandler) {
+			detachEvents({
+				client: this.client,
+				attached: this.eventHandler.attachedHandlers,
+			});
+		}
+
+		logger.info("HandlerManager shutdown complete.");
+	}
+
+	private registerShutdownSignals(): void {
+		const handler = (signal: string) => {
+			logger.info(`Received ${signal}. Shutting down...`);
+			this.shutdown();
+			process.exit(0);
+		};
+
+		process.once("SIGINT", () => handler("SIGINT"));
+		process.once("SIGTERM", () => handler("SIGTERM"));
+	}
+
+	private async registerApplicationCommands(): Promise<void> {
+		const plans: HandlerRegistrationPlan[] = [];
+
+		if (this.commandsConfig?.register && this.commandHandler) {
+			plans.push({
+				register: this.commandsConfig.register,
+				commandJson: this.commandHandler.toRegistrationJson(),
+				cache: this.commandsConfig.registrationCache ?? true,
+			});
+		}
+
+		if (this.contextMenusConfig?.register && this.contextMenuHandler) {
+			plans.push({
+				register: this.contextMenusConfig.register,
+				commandJson: this.contextMenuHandler.toRegistrationJson(),
+				cache: this.contextMenusConfig.registrationCache ?? true,
+			});
+		}
+
+		for (const plan of combineRegistrationPlans(plans)) {
+			await registerCommands({
+				token: plan.register.token,
+				applicationId: plan.register.applicationId,
+				where: plan.register.where,
+				commandJson: plan.commandJson,
+				cache: plan.cache,
+			});
+		}
+	}
+}

package/src/handler/manager/index.ts

@@ -0,0 +1,2 @@
+export type { HandlerManagerOptions } from "./HandlerManager";
+export { HandlerManager } from "./HandlerManager";