cordsmith 0.1.0

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

@@ -0,0 +1,18 @@
+import type { Precondition } from "../../../@types/precondition";
+
+export const OwnerOnly: Precondition = {
+	name: "OwnerOnly",
+	run({ meta, ownerIds, interaction }) {
+		if (!meta.ownerOnly) return { ok: true };
+
+		if (!ownerIds.has(interaction.user.id)) {
+			return {
+				ok: false,
+				message: "You can't use this command.",
+				ephemeral: true,
+			};
+		}
+
+		return { ok: true };
+	},
+};

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

@@ -0,0 +1,33 @@
+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 UserPermissions: Precondition = {
+	name: "UserPermissions",
+	run({ meta, interaction }) {
+		if (!meta.userPermissions?.length) return { ok: true };
+		if (!interaction.inGuild()) return { ok: true };
+
+		const memberPerms = interaction.memberPermissions;
+		const missing = missingPerms(
+			new Set(memberPerms?.toArray() ?? []),
+			meta.userPermissions,
+		);
+
+		if (missing.length > 0) {
+			return {
+				ok: false,
+				message: `You're missing permissions: ${missing.join(", ")}`,
+				ephemeral: true,
+			};
+		}
+
+		return { ok: true };
+	},
+};

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

@@ -0,0 +1,140 @@
+import { REST, Routes } from "discord.js";
+import { logger } from "../../../utils/logger";
+import {
+	hashCommandJson,
+	type RegisterScope,
+	readCachedHash,
+	writeCachedHash,
+} from "./commandCache";
+
+export type RegisterMode =
+	| { mode: "guild"; guildId: string }
+	| { mode: "global" }
+	| { mode: "none" };
+
+export async function registerCommands(options: {
+	token: string;
+	applicationId: string;
+	where: RegisterMode;
+	commandJson: unknown[];
+	/**
+	 * If true, compare hashes and skip REST registration when unchanged.
+	 * Defaults to true.
+	 */
+	cache?: boolean;
+
+	/**
+	 * If true, ALWAYS register regardless of cache.
+	 * Defaults to Bun.env.DISCORD_FORCE_REGISTER === "true".
+	 */
+	force?: boolean;
+
+	/**
+	 * Optional cache partition key (ex: "development" / "production").
+	 * If omitted, uses Bun.env.NODE_ENV (or undefined if not set).
+	 */
+	envKey?: string;
+}): Promise<void> {
+	const { token, applicationId, where, commandJson } = options;
+
+	const useCache = options.cache ?? true;
+	const force =
+		options.force ??
+		String(Bun.env.DISCORD_FORCE_REGISTER ?? "false").toLowerCase() === "true";
+
+	const envKey = options.envKey ?? Bun.env.NODE_ENV;
+
+	if (where.mode === "none") {
+		logger.info("Skipping command registration (mode: none).");
+		return;
+	}
+
+	const scope: RegisterScope =
+		where.mode === "global"
+			? { mode: "global" }
+			: { mode: "guild", guildId: where.guildId };
+
+	const scopeLabel =
+		scope.mode === "global" ? "global" : `guild ${scope.guildId}`;
+
+	// Single REST client instance shared across all registration paths below.
+	const rest = new REST({ version: "10" }).setToken(token);
+
+	if (useCache && !force) {
+		const nextHash = hashCommandJson(commandJson);
+		const prevHash = await readCachedHash({
+			scope,
+			applicationId,
+			envKey,
+		});
+
+		if (prevHash && prevHash === nextHash) {
+			logger.info(
+				`Command registration skipped (no changes) for ${scopeLabel}.`,
+			);
+			return;
+		}
+
+		logger.info(`Commands changed; registering for ${scopeLabel}...`);
+
+		if (where.mode === "guild") {
+			await rest.put(
+				Routes.applicationGuildCommands(applicationId, where.guildId),
+				{ body: commandJson },
+			);
+
+			await writeCachedHash({ scope, applicationId, envKey, hash: nextHash });
+
+			logger.info(
+				`Registered ${commandJson.length} guild application command(s) to ${where.guildId}.`,
+			);
+			return;
+		}
+
+		await rest.put(Routes.applicationCommands(applicationId), {
+			body: commandJson,
+		});
+
+		await writeCachedHash({ scope, applicationId, envKey, hash: nextHash });
+
+		logger.info(
+			`Registered ${commandJson.length} global application command(s). (Propagation can take time)`,
+		);
+		return;
+	}
+
+	// force=true intentionally bypasses the hash equality check and always
+	// registers, even when commands are unchanged. We still write the hash
+	// afterwards so the next normal startup can benefit from caching.
+	if (force) {
+		logger.warn(`Force register enabled; registering for ${scopeLabel}...`);
+	} else {
+		logger.info(`Registering for ${scopeLabel} (cache disabled)...`);
+	}
+
+	if (where.mode === "guild") {
+		await rest.put(
+			Routes.applicationGuildCommands(applicationId, where.guildId),
+			{ body: commandJson },
+		);
+
+		const nextHash = hashCommandJson(commandJson);
+		await writeCachedHash({ scope, applicationId, envKey, hash: nextHash });
+
+		logger.info(
+			`Registered ${commandJson.length} guild application command(s) to ${where.guildId}.`,
+		);
+		return;
+	}
+
+	await rest.put(Routes.applicationCommands(applicationId), {
+		body: commandJson,
+	});
+
+	const nextHash = hashCommandJson(commandJson);
+	await writeCachedHash({ scope, applicationId, envKey, hash: nextHash });
+
+	logger.info(
+		`Registered ${commandJson.length} global application command(s). (Propagation can take time)`,
+	);
+}

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

@@ -0,0 +1,103 @@
+import type {
+	Precondition,
+	PreconditionContext,
+	PreconditionResult,
+} from "../../@types/precondition";
+import { BotPermissions } from "./preconditions/BotPermissions";
+import { Cooldown } from "./preconditions/Cooldown";
+import { GuildOnly } from "./preconditions/GuildOnly";
+import { OwnerOnly } from "./preconditions/OwnerOnly";
+import { UserPermissions } from "./preconditions/UserPermissions";
+
+/**
+ * Built-in preconditions applied to every slash command automatically,
+ * based on the flags set in command meta. Order matters:
+ *
+ * 1. OwnerOnly     — bail early for non-owners before any other check
+ * 2. GuildOnly     — bail before guild-specific checks (perms, cooldowns)
+ * 3. Cooldown      — check + set cooldown before executing
+ * 4. UserPermissions
+ * 5. BotPermissions
+ */
+const BUILT_INS: Precondition[] = [
+	OwnerOnly,
+	GuildOnly,
+	Cooldown,
+	UserPermissions,
+	BotPermissions,
+];
+
+export type RunPreconditionsOptions = {
+	ctx: PreconditionContext;
+	/**
+	 * Custom preconditions registered on CommandHandler, keyed by name.
+	 * Only the ones listed in `ctx.meta.preconditions` will be run.
+	 */
+	registry: Map<string, Precondition>;
+};
+
+export type PreconditionFailure = {
+	message: string;
+	ephemeral: boolean;
+};
+
+export type RunPreconditionsResult =
+	| { ok: true }
+	| { ok: false; failure: PreconditionFailure };
+
+/**
+ * Runs all applicable preconditions for a slash command invocation.
+ *
+ * Built-ins always run first (in a fixed order) based on meta flags.
+ * Custom preconditions from `meta.preconditions` run afterwards, in the
+ * order they are declared on the command.
+ *
+ * Returns on the first failure — subsequent preconditions are not evaluated.
+ */
+export async function runPreconditions(
+	options: RunPreconditionsOptions,
+): Promise<RunPreconditionsResult> {
+	const { ctx, registry } = options;
+
+	// Run built-ins
+	for (const precondition of BUILT_INS) {
+		const result: PreconditionResult = await precondition.run(ctx);
+
+		if (!result.ok) {
+			return {
+				ok: false,
+				failure: {
+					message: result.message,
+					ephemeral: result.ephemeral ?? true,
+				},
+			};
+		}
+	}
+
+	// Run custom preconditions declared on this command
+	const customNames = ctx.meta.preconditions ?? [];
+
+	for (const name of customNames) {
+		const precondition = registry.get(name);
+
+		if (!precondition) {
+			throw new Error(
+				`Precondition "${name}" is referenced by command "${ctx.interaction.commandName}" but was never registered on CommandHandler.`,
+			);
+		}
+
+		const result: PreconditionResult = await precondition.run(ctx);
+
+		if (!result.ok) {
+			return {
+				ok: false,
+				failure: {
+					message: result.message,
+					ephemeral: result.ephemeral ?? true,
+				},
+			};
+		}
+	}
+
+	return { ok: true };
+}

package/src/handler/command/index.ts

@@ -0,0 +1,20 @@
+export type {
+	Precondition,
+	PreconditionContext,
+	PreconditionResult,
+} from "../@types/precondition";
+export type { CommandHandlerOptions } from "./CommandHandler";
+export { CommandHandler } from "./CommandHandler";
+export {
+	DISCORD_CUSTOM_ID_MAX_LENGTH,
+	makeCustomId,
+	parseCustomId,
+} from "./functions/customId";
+export { BotPermissions } from "./functions/preconditions/BotPermissions";
+export { Cooldown } from "./functions/preconditions/Cooldown";
+export { GuildOnly } from "./functions/preconditions/GuildOnly";
+// if they want to compose or extend them in custom preconditions.
+export { OwnerOnly } from "./functions/preconditions/OwnerOnly";
+export { UserPermissions } from "./functions/preconditions/UserPermissions";
+export type { RegisterMode } from "./functions/registerCommands";
+export { UserError } from "./functions/UserError";

package/src/handler/context/ContextMenuHandler.ts

@@ -0,0 +1,172 @@
+import { Collection, PermissionsBitField } from "discord.js";
+import type { ClientClass } from "../../structure/Client";
+import type { ContextMenuCommand } from "../@types/contextMenu";
+import type { Precondition } from "../@types/precondition";
+import { CooldownStore } from "../command/functions/cooldowns";
+import { parseOwnerIds } from "../command/functions/owners";
+import {
+	type RegisterMode,
+	registerCommands,
+} from "../command/functions/registerCommands";
+import {
+	type AttachedContextMenuListener,
+	attachContextMenuListener,
+} from "./functions/attachContextMenuListener";
+import { loadContextMenusFromDisk } from "./functions/loadContextMenus";
+
+export type ContextMenuHandlerOptions = {
+	client: ClientClass;
+
+	contextMenusDir: string;
+
+	register?: {
+		token: string;
+		applicationId: string;
+		where: RegisterMode;
+	};
+
+	extensions?: string[];
+
+	ownerIds?: string[];
+
+	/**
+	 * If true (default), skip REST registration when commands haven't changed.
+	 */
+	registrationCache?: boolean;
+};
+
+export class ContextMenuHandler {
+	public readonly commands = new Collection<string, ContextMenuCommand>();
+
+	private readonly client: ClientClass;
+	private readonly contextMenusDir: string;
+	private readonly registerConfig?: ContextMenuHandlerOptions["register"];
+	private readonly extensions: string[];
+	private readonly ownerIds: Set<string>;
+	private readonly cooldowns = new CooldownStore();
+	private readonly registrationCache: boolean;
+
+	/**
+	 * Shared precondition registry. If you pass the same Map instance used by
+	 * CommandHandler, all registered preconditions are available to both
+	 * slash commands and context menus automatically.
+	 */
+	private readonly preconditionRegistry: Map<string, Precondition>;
+	private attachedListener?: AttachedContextMenuListener;
+
+	private initialized = false;
+
+	constructor(
+		options: ContextMenuHandlerOptions & {
+			/**
+			 * Optionally pass CommandHandler's precondition registry to share
+			 * custom preconditions across both handlers.
+			 */
+			preconditionRegistry?: Map<string, Precondition>;
+		},
+	) {
+		this.client = options.client;
+		this.contextMenusDir = options.contextMenusDir;
+		this.registerConfig = options.register;
+		this.extensions = options.extensions ?? [".ts"];
+		this.preconditionRegistry =
+			options.preconditionRegistry ?? new Map<string, Precondition>();
+
+		this.ownerIds = options.ownerIds
+			? new Set(options.ownerIds)
+			: parseOwnerIds(Bun.env.DISCORD_OWNER_IDS);
+
+		this.registrationCache = options.registrationCache ?? true;
+	}
+
+	/**
+	 * Register a custom precondition so context menus can reference it by name.
+	 * Must be called before `init()`. 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.preconditionRegistry.has(precondition.name)) {
+			throw new Error(
+				`Precondition "${precondition.name}" is already registered.`,
+			);
+		}
+
+		this.preconditionRegistry.set(precondition.name, precondition);
+		return this;
+	}
+
+	public async init(): Promise<void> {
+		if (this.initialized) {
+			throw new Error("ContextMenuHandler.init() was called more than once.");
+		}
+		this.initialized = true;
+
+		const commands = await loadContextMenusFromDisk({
+			contextMenusDir: this.contextMenusDir,
+			extensions: this.extensions,
+		});
+
+		for (const [name, cmd] of commands) {
+			this.commands.set(name, cmd);
+		}
+
+		this.attachedListener = attachContextMenuListener({
+			client: this.client,
+			commands: this.commands,
+			ownerIds: this.ownerIds,
+			cooldowns: this.cooldowns,
+			preconditionRegistry: this.preconditionRegistry,
+		});
+
+		if (this.registerConfig) {
+			await registerCommands({
+				token: this.registerConfig.token,
+				applicationId: this.registerConfig.applicationId,
+				where: this.registerConfig.where,
+				commandJson: this.toRegistrationJson(),
+				cache: this.registrationCache,
+			});
+		}
+	}
+
+	public detach(): void {
+		if (!this.attachedListener) return;
+
+		this.client.off(
+			this.attachedListener.eventName,
+			this.attachedListener.fn as never,
+		);
+		this.attachedListener = undefined;
+	}
+
+	/**
+	 * Serialise to plain JSON for Discord registration.
+	 * Permissions are applied to the JSON object, not the builder,
+	 * so the in-memory store is never mutated as a side effect.
+	 * Sorted by name for a stable hash regardless of load order.
+	 */
+	public toRegistrationJson(): unknown[] {
+		const out: Array<Record<string, unknown>> = [];
+
+		for (const cmd of this.commands.values()) {
+			const json = cmd.data.toJSON() as unknown as Record<string, unknown>;
+
+			const perms = cmd.meta?.defaultMemberPermissions;
+			if (perms && perms.length > 0) {
+				const bitfield = new PermissionsBitField(perms).bitfield;
+				json.default_member_permissions = String(bitfield);
+			}
+
+			out.push(json);
+		}
+
+		return out.sort((a, b) =>
+			String(a.name ?? "").localeCompare(String(b.name ?? "")),
+		);
+	}
+}

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

@@ -0,0 +1,174 @@
+import type {
+	Collection,
+	InteractionReplyOptions,
+	MessageContextMenuCommandInteraction,
+	UserContextMenuCommandInteraction,
+} from "discord.js";
+import type { ClientClass } from "../../../structure/Client";
+import { logger } from "../../../utils";
+import type { ContextMenuCommand } from "../../@types/contextMenu";
+import type { Precondition } from "../../@types/precondition";
+import type { CooldownStore } from "../../command/functions/cooldowns";
+import { isUserError } from "../../command/functions/UserError";
+import { runContextMenuPreconditions } from "./runContextMenuPreconditions";
+
+type AnyContextMenuInteraction =
+	| UserContextMenuCommandInteraction
+	| MessageContextMenuCommandInteraction;
+
+type Repliable = {
+	deferred: boolean;
+	replied: boolean;
+	reply: (options: InteractionReplyOptions) => Promise<unknown>;
+	followUp: (options: InteractionReplyOptions) => Promise<unknown>;
+};
+
+export type AttachedContextMenuListener = {
+	eventName: "interactionCreate";
+	fn: (interaction: any) => void;
+};
+
+async function replySafe(
+	interaction: Repliable,
+	payload: InteractionReplyOptions,
+): Promise<void> {
+	if (interaction.deferred || interaction.replied) {
+		await interaction.followUp(payload);
+	} else {
+		await interaction.reply(payload);
+	}
+}
+
+/**
+ * Shared routing logic for both user and message context menu interactions.
+ * Previously duplicated across two identical blocks.
+ */
+async function routeContextMenuInteraction<
+	T extends AnyContextMenuInteraction,
+>(options: {
+	interaction: T;
+	command: ContextMenuCommand & {
+		execute: (ctx: { interaction: T; client: ClientClass }) => Promise<void>;
+	};
+	client: ClientClass;
+	ownerIds: Set<string>;
+	cooldowns: CooldownStore;
+	preconditionRegistry: Map<string, Precondition>;
+	label: string;
+}): Promise<void> {
+	const {
+		interaction,
+		command,
+		client,
+		ownerIds,
+		cooldowns,
+		preconditionRegistry,
+		label,
+	} = options;
+
+	const result = await runContextMenuPreconditions({
+		ctx: {
+			interaction,
+			client,
+			meta: command.meta ?? {},
+			ownerIds,
+			cooldowns,
+		},
+		registry: preconditionRegistry,
+	});
+
+	if (!result.ok) {
+		await replySafe(interaction, {
+			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 ${label} context menu "${interaction.commandName}"`,
+			err,
+		);
+
+		await replySafe(interaction, {
+			content: "Something went wrong.",
+			ephemeral: true,
+		});
+	}
+}
+
+export function attachContextMenuListener(options: {
+	client: ClientClass;
+	commands: Collection<string, ContextMenuCommand>;
+	ownerIds: Set<string>;
+	cooldowns: CooldownStore;
+	preconditionRegistry: Map<string, Precondition>;
+}): AttachedContextMenuListener {
+	const { client, commands, ownerIds, cooldowns, preconditionRegistry } =
+		options;
+
+	const fn = async (interaction: any) => {
+		// ---- User context menu ----
+		if (interaction.isUserContextMenuCommand()) {
+			const command = commands.get(interaction.commandName);
+
+			if (!command || command.type !== "user") {
+				logger.warn(
+					`Received unknown user context menu: "${interaction.commandName}"`,
+				);
+				return;
+			}
+
+			await routeContextMenuInteraction({
+				interaction,
+				command,
+				client,
+				ownerIds,
+				cooldowns,
+				preconditionRegistry,
+				label: "user",
+			});
+			return;
+		}
+
+		// ---- Message context menu ----
+		if (interaction.isMessageContextMenuCommand()) {
+			const command = commands.get(interaction.commandName);
+
+			if (!command || command.type !== "message") {
+				logger.warn(
+					`Received unknown message context menu: "${interaction.commandName}"`,
+				);
+				return;
+			}
+
+			await routeContextMenuInteraction({
+				interaction,
+				command,
+				client,
+				ownerIds,
+				cooldowns,
+				preconditionRegistry,
+				label: "message",
+			});
+		}
+	};
+
+	client.on("interactionCreate", fn);
+
+	return {
+		eventName: "interactionCreate",
+		fn,
+	};
+}