cordsmith 0.1.0

package/src/handler/command/functions/attachInteractionListener.ts

@@ -0,0 +1,271 @@
+import type {
+	Collection,
+	InteractionReplyOptions,
+	MessageComponentInteraction,
+	ModalSubmitInteraction,
+} from "discord.js";
+import type { ClientClass } from "../../../structure/Client";
+import { logger } from "../../../utils";
+import type { SlashCommand } from "../../@types/command";
+import type { Precondition } from "../../@types/precondition";
+import type { CooldownStore } from "./cooldowns";
+import { parseCustomId } from "./customId";
+import { runPreconditions } from "./runPreconditions";
+import { isUserError } from "./UserError";
+
+export type AttachedInteractionListener = {
+	eventName: "interactionCreate";
+	fn: (interaction: any) => void;
+};
+
+// RepliableInteraction from discord.js is a union of *concrete* narrowed types,
+// so the abstract base classes (MessageComponentInteraction etc.) aren't
+// assignable to it. This structural type targets only what replySafe actually
+// needs, which is both correct and sufficient.
+type Repliable = {
+	deferred: boolean;
+	replied: boolean;
+	reply: (options: InteractionReplyOptions) => Promise<unknown>;
+	followUp: (options: InteractionReplyOptions) => Promise<unknown>;
+};
+
+async function replySafe(
+	interaction: Repliable,
+	payload: InteractionReplyOptions,
+): Promise<void> {
+	if (interaction.deferred || interaction.replied) {
+		await interaction.followUp(payload);
+	} else {
+		await interaction.reply(payload);
+	}
+}
+
+function enforceComponentOwnerOnly(options: {
+	cmd: SlashCommand;
+	payload: string | undefined;
+	userId: string;
+}): { ok: true } | { ok: false; message: string } {
+	const { cmd, payload, userId } = options;
+
+	if (!cmd.meta?.componentOwnerOnly) return { ok: true };
+
+	if (!payload) {
+		return {
+			ok: false,
+			message:
+				"This interaction is missing an owner payload. Re-run the command.",
+		};
+	}
+
+	// Allow payload formats: "<userId>" or "<userId>:<anything>"
+	const ownerId = payload.split(":")[0];
+
+	if (ownerId !== userId) {
+		return { ok: false, message: "This interaction isn't for you." };
+	}
+
+	return { ok: true };
+}
+
+type ComponentCtx<T> = {
+	interaction: T;
+	client: ClientClass;
+	action: string;
+	payload?: string;
+};
+
+/**
+ * Shared routing logic for button, select menu, and modal interactions.
+ *
+ * Generic over T so each call site keeps its concrete interaction type,
+ * avoiding the contravariance errors that arise from a wide union handler type.
+ */
+async function routeComponentInteraction<
+	T extends MessageComponentInteraction | ModalSubmitInteraction,
+>(options: {
+	interaction: T;
+	commands: Collection<string, SlashCommand>;
+	client: ClientClass;
+	getHandler: (
+		cmd: SlashCommand,
+		action: string,
+	) => ((ctx: ComponentCtx<T>) => Promise<void>) | undefined;
+	label: string;
+}): Promise<void> {
+	const { interaction, commands, client, getHandler, label } = options;
+
+	const parsed = parseCustomId(interaction.customId);
+	if (!parsed.ok) return;
+
+	const cmd = commands.get(parsed.commandName);
+	if (!cmd) return;
+
+	const handler = getHandler(cmd, parsed.action);
+	if (!handler) return;
+
+	const ownerCheck = enforceComponentOwnerOnly({
+		cmd,
+		payload: parsed.payload,
+		userId: interaction.user.id,
+	});
+
+	if (!ownerCheck.ok) {
+		await replySafe(interaction, {
+			content: ownerCheck.message,
+			ephemeral: true,
+		});
+		return;
+	}
+
+	try {
+		await handler({
+			interaction,
+			client,
+			action: parsed.action,
+			payload: parsed.payload,
+		});
+	} catch (err) {
+		if (isUserError(err)) {
+			await replySafe(interaction, {
+				content: err.message,
+				ephemeral: err.ephemeral,
+			});
+			return;
+		}
+
+		logger.error(
+			`Error in ${label} handler for "${parsed.commandName}:${parsed.action}"`,
+			err,
+		);
+
+		await replySafe(interaction, {
+			content: "Something went wrong.",
+			ephemeral: true,
+		});
+	}
+}
+
+export function attachInteractionListener(options: {
+	client: ClientClass;
+	commands: Collection<string, SlashCommand>;
+	ownerIds: Set<string>;
+	cooldowns: CooldownStore;
+	preconditionRegistry: Map<string, Precondition>;
+}): AttachedInteractionListener {
+	const { client, commands, ownerIds, cooldowns, preconditionRegistry } =
+		options;
+
+	const fn = async (interaction: any) => {
+		// ---- Autocomplete routing ----
+		if (interaction.isAutocomplete()) {
+			const command = commands.get(interaction.commandName);
+			if (!command?.autocomplete) return;
+
+			try {
+				await command.autocomplete({ interaction, client });
+			} catch (err) {
+				logger.error(
+					`Error in autocomplete for "${interaction.commandName}"`,
+					err,
+				);
+			}
+
+			return;
+		}
+
+		// ---- Button routing ----
+		if (interaction.isButton()) {
+			await routeComponentInteraction({
+				interaction,
+				commands,
+				client,
+				getHandler: (cmd, action) => cmd.buttons?.[action],
+				label: "button",
+			});
+			return;
+		}
+
+		// ---- Select menu routing ----
+		if (interaction.isAnySelectMenu()) {
+			await routeComponentInteraction({
+				interaction,
+				commands,
+				client,
+				getHandler: (cmd, action) => cmd.selectMenus?.[action],
+				label: "select menu",
+			});
+			return;
+		}
+
+		// ---- Modal routing ----
+		if (interaction.isModalSubmit()) {
+			await routeComponentInteraction({
+				interaction,
+				commands,
+				client,
+				getHandler: (cmd, action) => cmd.modals?.[action],
+				label: "modal",
+			});
+			return;
+		}
+
+		// ---- Slash command routing ----
+		if (!interaction.isChatInputCommand()) return;
+
+		const command = commands.get(interaction.commandName);
+
+		if (!command) {
+			// Don't expose internal state to users — log it instead.
+			logger.warn(
+				`Received unknown slash command: "${interaction.commandName}"`,
+			);
+			return;
+		}
+
+		// Run all preconditions (built-ins + any custom ones declared on the command)
+		const result = await runPreconditions({
+			ctx: {
+				interaction,
+				client,
+				meta: command.meta ?? {},
+				ownerIds,
+				cooldowns,
+			},
+			registry: preconditionRegistry,
+		});
+
+		if (!result.ok) {
+			await interaction.reply({
+				content: result.failure.message,
+				ephemeral: result.failure.ephemeral,
+			});
+			return;
+		}
+
+		try {
+			await command.execute({ interaction, client });
+		} catch (err) {
+			if (isUserError(err)) {
+				await replySafe(interaction, {
+					content: err.message,
+					ephemeral: err.ephemeral,
+				});
+				return;
+			}
+
+			logger.error(`Error executing "${interaction.commandName}"`, err);
+
+			await replySafe(interaction, {
+				content: "Something went wrong while running that command.",
+				ephemeral: true,
+			});
+		}
+	};
+
+	client.on("interactionCreate", fn);
+
+	return {
+		eventName: "interactionCreate",
+		fn,
+	};
+}

package/src/handler/command/functions/commandCache.ts

@@ -0,0 +1,97 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export type RegisterScope =
+	| { mode: "guild"; guildId: string }
+	| { mode: "global" };
+
+function cacheDir(): string {
+	return path.join(process.cwd(), ".cache", "discord-commands");
+}
+
+function hashText(text: string): string {
+	return new Bun.CryptoHasher("sha256").update(text).digest("hex");
+}
+
+export function safeCacheComponent(value: string): string {
+	const safe = value
+		.replace(/[^A-Za-z0-9_.-]/g, "_")
+		.replace(/\.{2,}/g, "_");
+
+	if (safe === value && safe.length > 0) return safe;
+
+	const fallback = safe.replace(/^_+|_+$/g, "") || "value";
+	return `${fallback}.${hashText(value).slice(0, 12)}`;
+}
+
+function fileBaseName(options: {
+	scope: RegisterScope;
+	applicationId: string;
+	envKey?: string;
+}): string {
+	const { scope, applicationId, envKey } = options;
+
+	const applicationPart = safeCacheComponent(applicationId);
+	const envPart = envKey ? `.${safeCacheComponent(envKey)}` : "";
+
+	if (scope.mode === "global") {
+		return `global.${applicationPart}${envPart}.hash`;
+	}
+
+	return `guild.${safeCacheComponent(
+		scope.guildId,
+	)}.${applicationPart}${envPart}.hash`;
+}
+
+function hashFilePath(options: {
+	scope: RegisterScope;
+	applicationId: string;
+	envKey?: string;
+}): string {
+	return path.join(cacheDir(), fileBaseName(options));
+}
+
+async function ensureDirExists(dir: string): Promise<void> {
+	await mkdir(dir, { recursive: true });
+}
+
+export async function readCachedHash(options: {
+	scope: RegisterScope;
+	applicationId: string;
+	envKey?: string;
+}): Promise<string | null> {
+	const file = hashFilePath(options);
+
+	try {
+		const text = await Bun.file(file).text();
+		const trimmed = text.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	} catch {
+		return null;
+	}
+}
+
+export async function writeCachedHash(options: {
+	scope: RegisterScope;
+	applicationId: string;
+	hash: string;
+	envKey?: string;
+}): Promise<void> {
+	await ensureDirExists(cacheDir());
+
+	const file = hashFilePath({
+		scope: options.scope,
+		applicationId: options.applicationId,
+		envKey: options.envKey,
+	});
+
+	await Bun.write(file, `${options.hash}\n`);
+}
+
+/**
+ * Hash the final command JSON payload we send to Discord.
+ */
+export function hashCommandJson(commandJson: unknown[]): string {
+	const text = JSON.stringify(commandJson);
+	return hashText(text);
+}

package/src/handler/command/functions/cooldowns.ts

@@ -0,0 +1,93 @@
+export type CooldownScope = "user" | "guild" | "global";
+
+type Key = string;
+
+export type CooldownStoreOptions = {
+	maxEntries?: number;
+	pruneEvery?: number;
+};
+
+export class CooldownStore {
+	private readonly until = new Map<Key, number>();
+	private readonly maxEntries: number;
+	private readonly pruneEvery: number;
+	private operations = 0;
+
+	constructor(options: CooldownStoreOptions = {}) {
+		this.maxEntries = Math.max(1, options.maxEntries ?? 10_000);
+		this.pruneEvery = Math.max(1, options.pruneEvery ?? 100);
+	}
+
+	public get size(): number {
+		return this.until.size;
+	}
+
+	private buildKey(
+		commandName: string,
+		scope: CooldownScope,
+		userId: string,
+		guildId: string | null,
+	): Key {
+		switch (scope) {
+			case "user":
+				return `${commandName}:user:${userId}`;
+			case "guild":
+				// Fall back to userId if somehow called outside a guild
+				return `${commandName}:guild:${guildId ?? userId}`;
+			case "global":
+				return `${commandName}:global`;
+		}
+	}
+
+	public getRemainingMs(
+		commandName: string,
+		scope: CooldownScope,
+		userId: string,
+		guildId: string | null,
+	): number {
+		const key = this.buildKey(commandName, scope, userId, guildId);
+		const now = Date.now();
+		const end = this.until.get(key) ?? 0;
+		const remaining = Math.max(0, end - now);
+
+		// Prune expired entry on read to prevent unbounded memory growth
+		if (remaining === 0) this.until.delete(key);
+		this.pruneIfNeeded(now);
+
+		return remaining;
+	}
+
+	public set(
+		commandName: string,
+		scope: CooldownScope,
+		userId: string,
+		guildId: string | null,
+		cooldownMs: number,
+	): void {
+		const now = Date.now();
+		const key = this.buildKey(commandName, scope, userId, guildId);
+		this.until.set(key, now + cooldownMs);
+		this.pruneIfNeeded(now);
+	}
+
+	private pruneIfNeeded(now: number): void {
+		this.operations += 1;
+
+		if (
+			this.until.size <= this.maxEntries &&
+			this.operations % this.pruneEvery !== 0
+		) {
+			return;
+		}
+
+		for (const [key, expiresAt] of this.until) {
+			if (expiresAt <= now) this.until.delete(key);
+		}
+
+		while (this.until.size > this.maxEntries) {
+			const oldest = this.until.keys().next().value;
+			if (oldest === undefined) break;
+			this.until.delete(oldest);
+		}
+	}
+}

package/src/handler/command/functions/customId.ts

@@ -0,0 +1,78 @@
+export type ParsedCustomId =
+	| {
+			ok: true;
+			commandName: string;
+			action: string;
+			payload?: string;
+	  }
+	| {
+			ok: false;
+			reason: string;
+	  };
+
+export const DISCORD_CUSTOM_ID_MAX_LENGTH = 100;
+
+function validateSegment(label: string, value: string): void {
+	if (value.trim().length === 0) {
+		throw new Error(`${label} cannot be empty.`);
+	}
+
+	if (value.includes(":")) {
+		throw new Error(`${label} cannot contain ":".`);
+	}
+}
+
+/**
+ * Format: cmd:<commandName>:<action>[:<payload>]
+ */
+export function parseCustomId(customId: string): ParsedCustomId {
+	if (!customId.startsWith("cmd:")) {
+		return { ok: false, reason: "Not a cmd:* customId" };
+	}
+
+	// cmd:<command>:<action>[:<payload>]
+	const parts = customId.split(":");
+
+	if (parts.length < 3) {
+		return { ok: false, reason: "Invalid cmd customId format" };
+	}
+
+	const commandName = parts[1]?.trim();
+	const action = parts[2]?.trim();
+	const payload = parts.slice(3).join(":").trim();
+
+	if (!commandName) return { ok: false, reason: "Missing commandName" };
+	if (!action) return { ok: false, reason: "Missing action" };
+
+	return {
+		ok: true,
+		commandName,
+		action,
+		payload: payload.length > 0 ? payload : undefined,
+	};
+}
+
+/**
+ * Helper to build IDs consistently.
+ */
+export function makeCustomId(
+	commandName: string,
+	action: string,
+	payload?: string,
+): string {
+	validateSegment("commandName", commandName);
+	validateSegment("action", action);
+
+	const id =
+		payload === undefined || payload.length === 0
+			? `cmd:${commandName}:${action}`
+			: `cmd:${commandName}:${action}:${payload}`;
+
+	if (id.length > DISCORD_CUSTOM_ID_MAX_LENGTH) {
+		throw new Error(
+			`customId is ${id.length} characters; Discord allows at most ${DISCORD_CUSTOM_ID_MAX_LENGTH}.`,
+		);
+	}
+
+	return id;
+}

package/src/handler/command/functions/loadCommands.ts

@@ -0,0 +1,62 @@
+import { pathToFileURL } from "node:url";
+import { Collection } from "discord.js";
+import { logger } from "../../../utils";
+import type { SlashCommand } from "../../@types/command";
+import { discoverModuleFiles } from "../../utils/files";
+
+type LoadResult = {
+	commands: Collection<string, SlashCommand>;
+};
+
+function isSlashCommandModule(mod: unknown): mod is SlashCommand {
+	if (!mod || typeof mod !== "object") return false;
+
+	const m = mod as Partial<SlashCommand>;
+	return (
+		typeof m.execute === "function" &&
+		typeof m.data === "object" &&
+		typeof m.data?.toJSON === "function" &&
+		// Ensure data.name is present and non-empty so we never register a
+		// command under "undefined" or produce a confusing duplicate-name error
+		typeof (m.data as { name?: unknown }).name === "string" &&
+		((m.data as { name?: unknown }).name as string).length > 0
+	);
+}
+
+export async function loadCommandsFromDisk(options: {
+	commandsDir: string;
+	extensions: string[];
+}): Promise<LoadResult> {
+	const { rootDir, files } = await discoverModuleFiles({
+		dir: options.commandsDir,
+		extensions: options.extensions,
+	});
+
+	const commands = new Collection<string, SlashCommand>();
+	let loaded = 0;
+
+	for (const filePath of files) {
+		const fileUrl = pathToFileURL(filePath).href;
+		const imported = await import(fileUrl);
+		const cmd = imported.default;
+
+		if (!isSlashCommandModule(cmd)) {
+			logger.warn(`Skipping invalid command module: ${filePath}`);
+			continue;
+		}
+
+		const name = cmd.data.name;
+
+		if (commands.has(name)) {
+			throw new Error(
+				`Duplicate command name "${name}" detected: ${filePath}`,
+			);
+		}
+
+		commands.set(name, cmd);
+		loaded += 1;
+	}
+
+	logger.info(`Loaded ${loaded} slash command(s) from ${rootDir}`);
+	return { commands };
+}

package/src/handler/command/functions/owners.ts

@@ -0,0 +1,10 @@
+export function parseOwnerIds(raw: string | undefined): Set<string> {
+	if (!raw) return new Set();
+
+	const ids = raw
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean);
+
+	return new Set(ids);
+}

package/src/handler/command/functions/preconditions/BotPermissions.ts

@@ -0,0 +1,34 @@
+import type { PermissionsString } from "discord.js";
+import type { Precondition } from "../../../@types/precondition";
+
+function missingPerms(
+	has: ReadonlySet<string>,
+	required: PermissionsString[],
+): PermissionsString[] {
+	return required.filter((p) => !has.has(p));
+}
+
+export const BotPermissions: Precondition = {
+	name: "BotPermissions",
+	run({ meta, interaction }) {
+		if (!meta.botPermissions?.length) return { ok: true };
+		if (!interaction.inGuild()) return { ok: true };
+
+		const me = interaction.guild?.members.me;
+		const botPerms = me?.permissionsIn(interaction.channelId);
+		const missing = missingPerms(
+			new Set(botPerms?.toArray() ?? []),
+			meta.botPermissions,
+		);
+
+		if (missing.length > 0) {
+			return {
+				ok: false,
+				message: `I'm missing permissions: ${missing.join(", ")}`,
+				ephemeral: true,
+			};
+		}
+
+		return { ok: true };
+	},
+};

package/src/handler/command/functions/preconditions/Cooldown.ts

@@ -0,0 +1,37 @@
+import type { Precondition } from "../../../@types/precondition";
+
+export const Cooldown: Precondition = {
+	name: "Cooldown",
+	run({ meta, interaction, cooldowns }) {
+		if (!meta.cooldownMs || meta.cooldownMs <= 0) return { ok: true };
+
+		const scope = meta.cooldownScope ?? "user";
+		const guildId = interaction.guildId;
+
+		const remaining = cooldowns.getRemainingMs(
+			interaction.commandName,
+			scope,
+			interaction.user.id,
+			guildId,
+		);
+
+		if (remaining > 0) {
+			return {
+				ok: false,
+				message: `Please wait ${Math.ceil(remaining / 1000)}s before using this command again.`,
+				ephemeral: true,
+			};
+		}
+
+		// Set the cooldown now — after all other checks pass but before execute()
+		cooldowns.set(
+			interaction.commandName,
+			scope,
+			interaction.user.id,
+			guildId,
+			meta.cooldownMs,
+		);
+
+		return { ok: true };
+	},
+};

package/src/handler/command/functions/preconditions/GuildOnly.ts

@@ -0,0 +1,18 @@
+import type { Precondition } from "../../../@types/precondition";
+
+export const GuildOnly: Precondition = {
+	name: "GuildOnly",
+	run({ meta, interaction }) {
+		if (!meta.guildOnly) return { ok: true };
+
+		if (!interaction.inGuild()) {
+			return {
+				ok: false,
+				message: "This command can only be used in a server.",
+				ephemeral: true,
+			};
+		}
+
+		return { ok: true };
+	},
+};