cordsmith 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TDanks2000
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# Cordsmith
+
+Cordsmith is a Bun-first Discord.js handler library extracted from the T+C bot.
+It provides handlers for slash commands, context menus, events, scheduled tasks,
+shared preconditions, command registration caching, and component custom IDs.
+
+## Install locally with Bun
+
+```sh
+bun add cordsmith@file:../cordsmith
+```
+
+## Basic usage
+
+```ts
+import { HandlerManager } from "cordsmith";
+
+const handlers = new HandlerManager({
+	client,
+	commands: {
+		commandsDir: "src/commands",
+		extensions: [".ts", ".js"],
+		register: {
+			token: Bun.env.DISCORD_TOKEN!,
+			applicationId: Bun.env.DISCORD_APPLICATION_ID!,
+			where: { mode: "global" },
+		},
+	},
+	events: {
+		eventsDir: "src/events",
+		extensions: [".ts", ".js"],
+	},
+});
+
+await handlers.init();
+```
+
+## Production Notes
+
+- Keep module directories scoped to trusted command, event, context menu, and task code. Cordsmith validates extensions and skips files that resolve outside the configured root.
+- Use `makeCustomId()` for component IDs. It enforces Discord's 100 character limit and rejects segments that would break routing.
+- `HandlerManager` registers slash commands and context menus in one payload per Discord scope, so enabling both does not overwrite either set.
+- `HandlerManager.shutdown()` detaches event, command, and context menu listeners and cancels scheduled tasks for clean restarts.

package/package.json

@@ -0,0 +1,72 @@
+{
+	"name": "cordsmith",
+	"version": "0.1.0",
+	"description": "A Bun-first Discord.js handler for slash commands, context menus, events, and scheduled tasks.",
+	"author": "TDanks2000",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/TDanks2000/cordsmith.git"
+	},
+	"bugs": {
+		"url": "https://github.com/TDanks2000/cordsmith/issues"
+	},
+	"homepage": "https://github.com/TDanks2000/cordsmith#readme",
+	"keywords": [
+		"discord",
+		"discord.js",
+		"bun",
+		"handler",
+		"slash-commands",
+		"context-menu",
+		"events"
+	],
+	"type": "module",
+	"module": "./src/index.ts",
+	"types": "./src/index.ts",
+	"packageManager": "bun@1.3.13",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		},
+		"./command": {
+			"types": "./src/handler/command/index.ts",
+			"import": "./src/handler/command/index.ts"
+		},
+		"./context": {
+			"types": "./src/handler/context/index.ts",
+			"import": "./src/handler/context/index.ts"
+		},
+		"./events": {
+			"types": "./src/handler/events/index.ts",
+			"import": "./src/handler/events/index.ts"
+		},
+		"./manager": {
+			"types": "./src/handler/manager/index.ts",
+			"import": "./src/handler/manager/index.ts"
+		},
+		"./tasks": {
+			"types": "./src/handler/tasks/index.ts",
+			"import": "./src/handler/tasks/index.ts"
+		}
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"check": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"peerDependencies": {
+		"discord.js": "^14.26.3"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.13",
+		"@types/node": "^25.6.0",
+		"discord.js": "^14.26.3",
+		"typescript": "^6.0.3"
+	}
+}

package/src/handler/@types/command.ts

@@ -0,0 +1,79 @@
+import type {
+	AnySelectMenuInteraction,
+	AutocompleteInteraction,
+	ButtonInteraction,
+	ChatInputCommandInteraction,
+	ModalSubmitInteraction,
+	PermissionsString,
+} from "discord.js";
+import type { ClientClass } from "../../structure/Client";
+
+export type CommandMeta = {
+	guildOnly?: boolean;
+	ownerOnly?: boolean;
+
+	cooldownMs?: number;
+
+	/**
+	 * Whether the cooldown is scoped per-user (default), per-guild, or global.
+	 * - "user"  — each user gets their own cooldown bucket (default)
+	 * - "guild" — the whole guild shares one bucket
+	 * - "global" — every invocation shares one bucket regardless of who or where
+	 */
+	cooldownScope?: "user" | "guild" | "global";
+
+	userPermissions?: PermissionsString[];
+	botPermissions?: PermissionsString[];
+
+	defaultMemberPermissions?: PermissionsString[];
+
+	componentOwnerOnly?: boolean;
+
+	/**
+	 * Names of additional preconditions to run before execute().
+	 * Built-in preconditions (OwnerOnly, GuildOnly, Cooldown, UserPermissions,
+	 * BotPermissions) are applied automatically from the meta fields above —
+	 * you only need this for custom preconditions registered on CommandHandler.
+	 *
+	 * @example
+	 * meta: { preconditions: ["HasRole:moderator", "PremiumOnly"] }
+	 */
+	preconditions?: string[];
+};
+
+export type SlashCommandData = {
+	name: string;
+	toJSON: () => unknown;
+};
+
+export type CommandContext<TInteraction, TClient = ClientClass> = {
+	interaction: TInteraction;
+	client: TClient;
+};
+
+export type ComponentHandler<TInteraction, TClient = ClientClass> = (ctx: {
+	interaction: TInteraction;
+	client: TClient;
+	action: string;
+	payload?: string;
+}) => Promise<void>;
+
+export type SlashCommand<TClient = ClientClass> = {
+	data: SlashCommandData;
+	meta?: CommandMeta;
+
+	execute: (
+		ctx: CommandContext<ChatInputCommandInteraction, TClient>,
+	) => Promise<void>;
+
+	autocomplete?: (
+		ctx: CommandContext<AutocompleteInteraction, TClient>,
+	) => Promise<void>;
+
+	buttons?: Record<string, ComponentHandler<ButtonInteraction, TClient>>;
+	selectMenus?: Record<
+		string,
+		ComponentHandler<AnySelectMenuInteraction, TClient>
+	>;
+	modals?: Record<string, ComponentHandler<ModalSubmitInteraction, TClient>>;
+};

package/src/handler/@types/contextMenu.ts

@@ -0,0 +1,80 @@
+import type {
+	MessageContextMenuCommandInteraction,
+	PermissionsString,
+	UserContextMenuCommandInteraction,
+} from "discord.js";
+import type { ClientClass } from "../../structure/Client";
+
+export type ContextMenuMeta = {
+	guildOnly?: boolean;
+	ownerOnly?: boolean;
+	cooldownMs?: number;
+	cooldownScope?: "user" | "guild" | "global";
+	userPermissions?: PermissionsString[];
+	botPermissions?: PermissionsString[];
+	defaultMemberPermissions?: PermissionsString[];
+
+	/**
+	 * Names of custom preconditions to run before execute().
+	 */
+	preconditions?: string[];
+};
+
+export type ContextMenuCommandData = {
+	name: string;
+	toJSON: () => unknown;
+};
+
+export type UserContextMenuCommand<TClient = ClientClass> = {
+	type: "user";
+	data: ContextMenuCommandData;
+	meta?: ContextMenuMeta;
+	execute: (ctx: {
+		interaction: UserContextMenuCommandInteraction;
+		client: TClient;
+	}) => Promise<void>;
+};
+
+export type MessageContextMenuCommand<TClient = ClientClass> = {
+	type: "message";
+	data: ContextMenuCommandData;
+	meta?: ContextMenuMeta;
+	execute: (ctx: {
+		interaction: MessageContextMenuCommandInteraction;
+		client: TClient;
+	}) => Promise<void>;
+};
+
+export type ContextMenuCommand<TClient = ClientClass> =
+	| UserContextMenuCommand<TClient>
+	| MessageContextMenuCommand<TClient>;
+
+/**
+ * Helper for type-safe user context menu command definitions.
+ *
+ * Usage:
+ * export default defineUserContextMenu({
+ *   data: new ContextMenuCommandBuilder().setName("Get Avatar"),
+ *   async execute({ interaction, client }) {}
+ * })
+ */
+export function defineUserContextMenu(
+	cmd: Omit<UserContextMenuCommand, "type">,
+): UserContextMenuCommand {
+	return { ...cmd, type: "user" };
+}
+
+/**
+ * Helper for type-safe message context menu command definitions.
+ *
+ * Usage:
+ * export default defineMessageContextMenu({
+ *   data: new ContextMenuCommandBuilder().setName("Translate"),
+ *   async execute({ interaction, client }) {}
+ * })
+ */
+export function defineMessageContextMenu(
+	cmd: Omit<MessageContextMenuCommand, "type">,
+): MessageContextMenuCommand {
+	return { ...cmd, type: "message" };
+}

package/src/handler/@types/event.ts

@@ -0,0 +1,37 @@
+import type { ClientEvents } from "discord.js";
+import type { ClientClass } from "../../structure/Client";
+
+export type EventName = keyof ClientEvents;
+
+export type EventListenerModule<
+	K extends EventName = EventName,
+	TClient = ClientClass,
+> = {
+	once?: boolean;
+	enabled?: boolean;
+	order?: number;
+
+	execute: (ctx: {
+		client: TClient;
+		args: ClientEvents[K];
+	}) => Promise<void>;
+};
+
+/**
+ * Helper for better type inference in event files.
+ *
+ * Usage:
+ * export default defineEvent({
+ *   name: "ready",
+ *   once: true,
+ *   async execute({ client }) {}
+ * })
+ *
+ * Note: "name" is inferred from the folder, not required here; this helper
+ * simply improves typing for args and ctx.
+ */
+export function defineEvent<K extends EventName>(
+	mod: EventListenerModule<K>,
+): EventListenerModule<K> {
+	return mod;
+}

package/src/handler/@types/precondition.ts

@@ -0,0 +1,28 @@
+import type { ChatInputCommandInteraction } from "discord.js";
+import type { ClientClass } from "../../structure/Client";
+import type { CooldownStore } from "../command/functions/cooldowns";
+import type { CommandMeta } from "./command";
+
+export type PreconditionResult =
+	| { ok: true }
+	| { ok: false; message: string; ephemeral?: boolean };
+
+export type PreconditionContext = {
+	interaction: ChatInputCommandInteraction;
+	client: ClientClass;
+	meta: CommandMeta;
+	ownerIds: Set<string>;
+	cooldowns: CooldownStore;
+};
+
+export type Precondition = {
+	/**
+	 * Unique name used to reference this precondition in command meta.
+	 * e.g. "GuildOnly", "HasRole:moderator"
+	 */
+	readonly name: string;
+
+	run: (
+		ctx: PreconditionContext,
+	) => Promise<PreconditionResult> | PreconditionResult;
+};

package/src/handler/@types/task.ts

@@ -0,0 +1,69 @@
+import type { ClientClass } from "../../structure/Client";
+
+export type TaskContext<TClient = ClientClass> = {
+	client: TClient;
+};
+
+export type TaskModule<TClient = ClientClass> = {
+	/**
+	 * Human-readable name shown in logs.
+	 * Inferred from the filename if not provided.
+	 */
+	name?: string;
+
+	/**
+	 * How often the task runs, in milliseconds.
+	 *
+	 * Alternatively, provide a cron expression via `cron`.
+	 * Exactly one of `intervalMs` or `cron` must be set.
+	 */
+	intervalMs?: number;
+
+	/**
+	 * Cron expression (standard 5-field: "min hour dom mon dow").
+	 *
+	 * Examples:
+	 *   "0 * * * *"   — every hour on the hour
+	 *   "30 9 * * 1"  — every Monday at 09:30
+	 *   "* /5 * * * *" — every 5 minutes
+	 *
+	 * Requires `intervalMs` to be unset.
+	 */
+	cron?: string;
+
+	/**
+	 * Whether to run the task immediately on startup before the first
+	 * interval/cron tick. Defaults to false.
+	 */
+	runOnStart?: boolean;
+
+	/**
+	 * If false, the task is loaded but never scheduled. Defaults to true.
+	 */
+	enabled?: boolean;
+
+	execute: (ctx: TaskContext<TClient>) => Promise<void>;
+};
+
+export type LoadedTask<TClient = ClientClass> = {
+	name: string;
+	filePath: string;
+	intervalMs?: number;
+	cron?: string;
+	runOnStart: boolean;
+	execute: TaskModule<TClient>["execute"];
+};
+
+/**
+ * Helper for better type inference in task files.
+ *
+ * Usage:
+ * export default defineTask({
+ *   intervalMs: 60_000,
+ *   runOnStart: true,
+ *   async execute({ client }) {}
+ * })
+ */
+export function defineTask(mod: TaskModule): TaskModule {
+	return mod;
+}

package/src/handler/command/CommandHandler.ts

@@ -0,0 +1,192 @@
+import { Collection, PermissionsBitField } from "discord.js";
+import type { ClientClass } from "../../structure/Client";
+import type { SlashCommand } from "../@types/command";
+import type { Precondition } from "../@types/precondition";
+import {
+	type AttachedInteractionListener,
+	attachInteractionListener,
+} from "./functions/attachInteractionListener";
+import { CooldownStore } from "./functions/cooldowns";
+import { loadCommandsFromDisk } from "./functions/loadCommands";
+import { parseOwnerIds } from "./functions/owners";
+import {
+	type RegisterMode,
+	registerCommands,
+} from "./functions/registerCommands";
+
+export type CommandHandlerOptions = {
+	client: ClientClass;
+
+	commandsDir: 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;
+
+	/**
+	 * Optionally provide an external precondition registry (e.g. from
+	 * HandlerManager) so preconditions are shared across multiple handlers.
+	 * If omitted, a fresh registry is created for this handler only.
+	 */
+	preconditionRegistry?: Map<string, Precondition>;
+};
+
+export class CommandHandler {
+	public readonly commands = new Collection<string, SlashCommand>();
+
+	private readonly client: ClientClass;
+	private readonly commandsDir: string;
+	private readonly registerConfig?: CommandHandlerOptions["register"];
+	private readonly extensions: string[];
+	private readonly ownerIds: Set<string>;
+	private readonly cooldowns = new CooldownStore();
+	private readonly registrationCache: boolean;
+
+	/**
+	 * Registry of custom preconditions, keyed by name.
+	 * Built-ins (OwnerOnly, GuildOnly, Cooldown, UserPermissions, BotPermissions)
+	 * are applied automatically and do not need to be registered here.
+	 */
+	private readonly preconditionRegistry: Map<string, Precondition>;
+	private attachedListener?: AttachedInteractionListener;
+
+	private initialized = false;
+
+	constructor(options: CommandHandlerOptions) {
+		this.client = options.client;
+		this.commandsDir = options.commandsDir;
+		this.registerConfig = options.register;
+		this.extensions = options.extensions ?? [".ts"];
+
+		this.ownerIds = options.ownerIds
+			? new Set(options.ownerIds)
+			: parseOwnerIds(Bun.env.DISCORD_OWNER_IDS);
+
+		this.registrationCache = options.registrationCache ?? true;
+
+		// Use a shared registry if provided (e.g. from HandlerManager),
+		// otherwise create a fresh one scoped to this handler.
+		this.preconditionRegistry =
+			options.preconditionRegistry ?? new Map<string, Precondition>();
+	}
+
+	/**
+	 * Register a custom precondition so commands can reference it by name
+	 * in their `meta.preconditions` array.
+	 *
+	 * Must be called before `init()`.
+	 *
+	 * Returns `this` for chaining:
+	 * ```ts
+	 * handler
+	 *   .registerPrecondition(PremiumOnly)
+	 *   .registerPrecondition(HasRole)
+	 *   .init();
+	 * ```
+	 */
+	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("CommandHandler.init() was called more than once.");
+		}
+		this.initialized = true;
+
+		const { commands } = await loadCommandsFromDisk({
+			commandsDir: this.commandsDir,
+			extensions: this.extensions,
+		});
+
+		for (const [name, cmd] of commands) {
+			this.commands.set(name, cmd);
+		}
+
+		this.attachedListener = attachInteractionListener({
+			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 commands to plain JSON for Discord registration.
+	 *
+	 * Permissions are applied to the serialised JSON object rather than the
+	 * builder so we never mutate the in-memory command store as a side effect.
+	 *
+	 * Commands are sorted by name before serialisation so the hash is stable
+	 * regardless of the order files are discovered on disk — without this, adding
+	 * a command that glob-sorts before an existing one changes the array order,
+	 * which changes the hash and can cause spurious re-registrations or missed
+	 * registrations depending on the cache state.
+	 */
+	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);
+		}
+
+		// Sort by name for a stable hash across different load orders
+		return out.sort((a, b) =>
+			String(a.name ?? "").localeCompare(String(b.name ?? "")),
+		);
+	}
+}

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

@@ -0,0 +1,13 @@
+export class UserError extends Error {
+	public readonly ephemeral: boolean;
+
+	constructor(message: string, options?: { ephemeral?: boolean }) {
+		super(message);
+		this.name = "UserError";
+		this.ephemeral = options?.ephemeral ?? true;
+	}
+}
+
+export function isUserError(err: unknown): err is UserError {
+	return err instanceof UserError;
+}