cordsmith 0.1.0

package/src/handler/manager/registrationPlans.ts

@@ -0,0 +1,58 @@
+import type { RegisterMode } from "../command/functions/registerCommands";
+
+export type HandlerRegistrationPlan = {
+	register: {
+		token: string;
+		applicationId: string;
+		where: RegisterMode;
+	};
+	commandJson: unknown[];
+	cache: boolean;
+};
+
+export type CombinedRegistrationPlan = HandlerRegistrationPlan;
+
+function whereKey(where: RegisterMode): string {
+	switch (where.mode) {
+		case "none":
+			return "none";
+		case "global":
+			return "global";
+		case "guild":
+			return `guild:${where.guildId}`;
+	}
+}
+
+function registrationKey(plan: HandlerRegistrationPlan): string {
+	const { register } = plan;
+	return [
+		register.token,
+		register.applicationId,
+		whereKey(register.where),
+	].join("\0");
+}
+
+export function combineRegistrationPlans(
+	plans: HandlerRegistrationPlan[],
+): CombinedRegistrationPlan[] {
+	const grouped = new Map<string, CombinedRegistrationPlan>();
+
+	for (const plan of plans) {
+		const key = registrationKey(plan);
+		const existing = grouped.get(key);
+
+		if (!existing) {
+			grouped.set(key, {
+				register: plan.register,
+				commandJson: [...plan.commandJson],
+				cache: plan.cache,
+			});
+			continue;
+		}
+
+		existing.commandJson.push(...plan.commandJson);
+		existing.cache = existing.cache && plan.cache;
+	}
+
+	return [...grouped.values()];
+}

package/src/handler/tasks/TaskHandler.ts

@@ -0,0 +1,73 @@
+import type { ClientClass } from "../../structure/Client";
+import { logger } from "../../utils";
+import type { LoadedTask } from "../@types/task";
+import { loadTasksFromDisk } from "./functions/loadTasks";
+import { scheduleTask, type TaskHandle } from "./functions/scheduleTask";
+
+export type TaskHandlerOptions = {
+	client: ClientClass;
+	tasksDir: string;
+	extensions?: string[];
+};
+
+export class TaskHandler {
+	private readonly client: ClientClass;
+	private readonly tasksDir: string;
+	private readonly extensions: string[];
+
+	public readonly tasks: LoadedTask[] = [];
+	private readonly handles: TaskHandle[] = [];
+
+	private initialized = false;
+
+	constructor(options: TaskHandlerOptions) {
+		this.client = options.client;
+		this.tasksDir = options.tasksDir;
+		this.extensions = options.extensions ?? [".ts"];
+	}
+
+	public async init(): Promise<void> {
+		if (this.initialized) {
+			throw new Error("TaskHandler.init() was called more than once.");
+		}
+		this.initialized = true;
+
+		const loaded = await loadTasksFromDisk({
+			tasksDir: this.tasksDir,
+			extensions: this.extensions,
+		});
+
+		for (const task of loaded) {
+			this.tasks.push(task);
+
+			const handle = scheduleTask(task, { client: this.client });
+			this.handles.push(handle);
+		}
+	}
+
+	/**
+	 * Cancel all running tasks and clear their timers.
+	 * Useful for graceful shutdown or hot-reload scenarios.
+	 */
+	public cancelAll(): void {
+		for (const handle of this.handles) {
+			handle.cancel();
+		}
+		this.handles.length = 0;
+		logger.info("All tasks cancelled.");
+	}
+
+	/**
+	 * Cancel a single task by name.
+	 * Returns true if found and cancelled, false otherwise.
+	 */
+	public cancel(name: string): boolean {
+		const handle = this.handles.find((h) => h.name === name);
+
+		if (!handle) return false;
+
+		handle.cancel();
+		this.handles.splice(this.handles.indexOf(handle), 1);
+		return true;
+	}
+}

package/src/handler/tasks/functions/loadTasks.ts

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { logger } from "../../../utils";
+import type { LoadedTask, TaskModule } from "../../@types/task";
+import { discoverModuleFiles } from "../../utils/files";
+
+function isTaskModule(mod: unknown): mod is TaskModule {
+	if (!mod || typeof mod !== "object") return false;
+
+	const m = mod as Partial<TaskModule>;
+
+	if (typeof m.execute !== "function") return false;
+
+	const hasInterval = typeof m.intervalMs === "number" && m.intervalMs > 0;
+	const hasCron = typeof m.cron === "string" && m.cron.trim().length > 0;
+
+	// Must have exactly one scheduling strategy
+	if (!hasInterval && !hasCron) return false;
+	if (hasInterval && hasCron) return false;
+
+	return true;
+}
+
+function nameFromFilePath(tasksDir: string, filePath: string): string {
+	const rel = path.relative(tasksDir, filePath).replace(/\\/g, "/");
+	// Strip extension: "cleanup/oldMessages.ts" → "cleanup/oldMessages"
+	return rel.replace(/\.[^/.]+$/, "");
+}
+
+export async function loadTasksFromDisk(options: {
+	tasksDir: string;
+	extensions: string[];
+}): Promise<LoadedTask[]> {
+	const { rootDir, files } = await discoverModuleFiles({
+		dir: options.tasksDir,
+		extensions: options.extensions,
+	});
+	const tasks: LoadedTask[] = [];
+	let loaded = 0;
+
+	for (const filePath of files) {
+		const fileUrl = pathToFileURL(filePath).href;
+		const imported = await import(fileUrl);
+		const mod = imported.default;
+
+		if (!isTaskModule(mod)) {
+			logger.warn(`Skipping invalid task module: ${filePath}`);
+			continue;
+		}
+
+		if (mod.enabled === false) continue;
+
+		const name = mod.name ?? nameFromFilePath(rootDir, filePath);
+
+		// Bug fix: duplicate names caused TaskHandler.cancel(name) to only
+		// ever find the first match, leaving the second task running silently.
+		if (tasks.some((t) => t.name === name)) {
+			throw new Error(`Duplicate task name "${name}" detected: ${filePath}`);
+		}
+
+		tasks.push({
+			name,
+			filePath,
+			intervalMs: mod.intervalMs,
+			cron: mod.cron,
+			runOnStart: mod.runOnStart ?? false,
+			execute: mod.execute,
+		});
+
+		loaded += 1;
+	}
+
+	logger.info(`Loaded ${loaded} task(s) from ${rootDir}`);
+	return tasks;
+}

package/src/handler/tasks/functions/parseCron.ts

@@ -0,0 +1,187 @@
+/**
+ * Lightweight cron expression parser.
+ *
+ * Supports standard 5-field cron: "min hour dom mon dow"
+ * Fields support: "*", numbers, ranges (1-5), steps (* /5, 1-5/2), and lists (1,3,5).
+ *
+ * Does NOT support @yearly/@monthly/@weekly/@daily/@hourly aliases or
+ * 6-field (seconds) expressions. Use intervalMs for sub-minute precision.
+ */
+
+type CronField = {
+	values: Set<number>;
+};
+
+function parseField(field: string, min: number, max: number): CronField {
+	const values = new Set<number>();
+
+	for (const rawPart of field.split(",")) {
+		const part = rawPart.trim();
+
+		if (part.length === 0) {
+			throw new Error(`Empty value in cron field "${field}".`);
+		}
+
+		if (part === "*") {
+			for (let i = min; i <= max; i++) values.add(i);
+			continue;
+		}
+
+		const stepMatch = part.match(/^(\*|\d+(?:-\d+)?)\/(\d+)$/);
+		if (stepMatch) {
+			const [, range, stepStr] = stepMatch;
+			const step = Number(stepStr);
+
+			// Bug fix: step=0 would cause an infinite loop in the for-loop below
+			if (step <= 0) {
+				throw new Error(
+					`Invalid step value "${stepStr}" in cron field "${field}": step must be >= 1.`,
+				);
+			}
+
+			const rangePart = range ?? "*";
+			const [start, end] =
+				rangePart === "*"
+					? [min, max]
+					: rangePart.includes("-")
+						? (rangePart.split("-").map(Number) as [number, number])
+						: [Number(rangePart), Number(rangePart)];
+
+			if (
+				!Number.isInteger(start) ||
+				!Number.isInteger(end) ||
+				start < min ||
+				end > max ||
+				start > end
+			) {
+				throw new Error(
+					`Invalid stepped range "${rangePart}" in cron field "${field}": must be within [${min}-${max}].`,
+				);
+			}
+
+			for (let i = start; i <= end; i += step) {
+				values.add(i);
+			}
+			continue;
+		}
+
+		const rangeMatch = part.match(/^(\d+)-(\d+)$/);
+		if (rangeMatch) {
+			const start = Number(rangeMatch[1]);
+			const end = Number(rangeMatch[2]);
+
+			// Bug fix: out-of-range ranges were silently ignored, task would never fire
+			if (start < min || end > max || start > end) {
+				throw new Error(
+					`Invalid range "${part}" in cron field "${field}": must be within [${min}-${max}].`,
+				);
+			}
+
+			for (let i = start; i <= end; i++) values.add(i);
+			continue;
+		}
+
+		if (/^\d+$/.test(part)) {
+			const num = Number(part);
+
+			if (!Number.isInteger(num) || num < min || num > max) {
+				throw new Error(
+					`Value ${num} is out of range [${min}-${max}] in cron field "${field}".`,
+				);
+			}
+
+			values.add(num);
+			continue;
+		}
+
+		throw new Error(`Invalid token "${part}" in cron field "${field}".`);
+	}
+
+	return { values };
+}
+
+export type ParsedCron = {
+	minute: CronField;
+	hour: CronField;
+	dom: CronField; // day of month
+	month: CronField;
+	dow: CronField; // day of week
+};
+
+export function parseCron(expression: string): ParsedCron {
+	const parts = expression.trim().split(/\s+/);
+
+	if (parts.length !== 5) {
+		throw new Error(
+			`Invalid cron expression "${expression}": expected 5 fields, got ${parts.length}.`,
+		);
+	}
+
+	const [minute, hour, dom, month, dow] = parts as [
+		string,
+		string,
+		string,
+		string,
+		string,
+	];
+
+	return {
+		minute: parseField(minute, 0, 59),
+		hour: parseField(hour, 0, 23),
+		dom: parseField(dom, 1, 31),
+		month: parseField(month, 1, 12),
+		dow: parseField(dow, 0, 6),
+	};
+}
+
+/**
+ * Returns the number of milliseconds until the next tick of a cron expression.
+ *
+ * Uses a skip-ahead strategy instead of iterating minute-by-minute.
+ * For sparse expressions like "0 0 1 1 *" (once a year), the old approach
+ * iterated up to 525,960 times per reschedule. Now:
+ *   - month/dom/dow mismatch → jump to midnight of the next day  (O(366) worst case)
+ *   - hour mismatch          → jump to the next hour             (O(24) per day)
+ *   - minute mismatch        → advance one minute                (O(60) per hour)
+ */
+export function msUntilNextCronTick(
+	parsed: ParsedCron,
+	from: Date = new Date(),
+): number {
+	// Start from the next whole minute
+	const candidate = new Date(from);
+	candidate.setSeconds(0, 0);
+	candidate.setMinutes(candidate.getMinutes() + 1);
+
+	const limit = new Date(from.getTime() + 366 * 24 * 60 * 60 * 1000);
+
+	while (candidate < limit) {
+		// Month, dom, or dow mismatch — jump to midnight of the next day
+		if (
+			!parsed.month.values.has(candidate.getMonth() + 1) ||
+			!parsed.dom.values.has(candidate.getDate()) ||
+			!parsed.dow.values.has(candidate.getDay())
+		) {
+			candidate.setDate(candidate.getDate() + 1);
+			candidate.setHours(0, 0, 0, 0);
+			continue;
+		}
+
+		// Hour mismatch — jump to the next hour
+		if (!parsed.hour.values.has(candidate.getHours())) {
+			candidate.setHours(candidate.getHours() + 1, 0, 0, 0);
+			continue;
+		}
+
+		// Matching day + hour — check minute
+		if (parsed.minute.values.has(candidate.getMinutes())) {
+			return candidate.getTime() - from.getTime();
+		}
+
+		candidate.setMinutes(candidate.getMinutes() + 1);
+	}
+
+	throw new Error(
+		`Could not find next tick for cron expression within 366 days.`,
+	);
+}

package/src/handler/tasks/functions/scheduleTask.ts

@@ -0,0 +1,106 @@
+import { logger } from "../../../utils";
+import type { LoadedTask, TaskContext } from "../../@types/task";
+import { msUntilNextCronTick, parseCron } from "./parseCron";
+
+export type TaskHandle = {
+	name: string;
+	cancel: () => void;
+};
+
+/**
+ * Schedules a single task and returns a handle to cancel it.
+ *
+ * Interval tasks use a self-rescheduling setTimeout rather than setInterval
+ * so a slow execution cannot overlap with the next run — the next tick is only
+ * scheduled after the current one completes.
+ *
+ * Cron tasks use a chain of setTimeout calls, recalculating the next tick
+ * each time so the schedule stays accurate across DST changes and variable
+ * month lengths.
+ */
+export function scheduleTask(task: LoadedTask, ctx: TaskContext): TaskHandle {
+	let cancelled = false;
+	// Track the active timer and its type separately so we call the correct
+	// clear function — calling clearInterval on a setTimeout id is a no-op in
+	// most runtimes but is semantically wrong and confusing.
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	let timerType: "timeout" | "interval" | null = null;
+	let running = false;
+
+	async function run(): Promise<void> {
+		if (cancelled) return;
+		if (running) return;
+
+		running = true;
+		try {
+			await task.execute(ctx);
+		} catch (err) {
+			logger.error(`Error in task "${task.name}"`, err);
+		} finally {
+			running = false;
+		}
+	}
+
+	function cancelTimer(): void {
+		if (timer === null) return;
+		if (timerType === "interval") {
+			clearInterval(timer);
+		} else {
+			clearTimeout(timer);
+		}
+		timer = null;
+		timerType = null;
+	}
+
+	if (task.intervalMs) {
+		const intervalMs = task.intervalMs;
+
+		async function scheduleNextInterval(): Promise<void> {
+			if (cancelled) return;
+			const start = Date.now();
+			await run();
+			if (cancelled) return;
+			const elapsed = Date.now() - start;
+			const delay = Math.max(0, intervalMs - elapsed);
+			timer = setTimeout(scheduleNextInterval, delay);
+			timerType = "timeout";
+		}
+
+		timer = setTimeout(
+			scheduleNextInterval,
+			task.runOnStart ? 0 : intervalMs,
+		);
+		timerType = "timeout";
+
+		logger.info(`Scheduled task "${task.name}" every ${intervalMs}ms.`);
+	} else if (task.cron) {
+		const parsed = parseCron(task.cron);
+
+		if (task.runOnStart) {
+			void run();
+		}
+
+		function scheduleNextCronTick(): void {
+			if (cancelled) return;
+			const delay = msUntilNextCronTick(parsed);
+			timer = setTimeout(async () => {
+				await run();
+				scheduleNextCronTick();
+			}, delay);
+			timerType = "timeout";
+		}
+
+		scheduleNextCronTick();
+
+		logger.info(`Scheduled task "${task.name}" with cron "${task.cron}".`);
+	}
+
+	return {
+		name: task.name,
+		cancel(): void {
+			cancelled = true;
+			cancelTimer();
+			logger.info(`Cancelled task "${task.name}".`);
+		},
+	};
+}

package/src/handler/tasks/index.ts

@@ -0,0 +1,4 @@
+export type { LoadedTask, TaskContext, TaskModule } from "../@types/task";
+export { defineTask } from "../@types/task";
+export type { TaskHandlerOptions } from "./TaskHandler";
+export { TaskHandler } from "./TaskHandler";

package/src/handler/utils/env.ts

@@ -0,0 +1,7 @@
+export function requireEnv(name: string): string {
+	const value = Bun.env[name];
+	if (!value || value.trim().length === 0) {
+		throw new Error(`Missing required env var: ${name}`);
+	}
+	return value;
+}

package/src/handler/utils/files.ts

@@ -0,0 +1,74 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+
+export type DiscoveredModuleFiles = {
+	rootDir: string;
+	files: string[];
+};
+
+const EXTENSION_PATTERN = /^\.[A-Za-z0-9]+$/;
+
+function resolveDir(dir: string): string {
+	return path.isAbsolute(dir) ? dir : path.resolve(process.cwd(), dir);
+}
+
+function isInsideDir(rootDir: string, filePath: string): boolean {
+	const rel = path.relative(rootDir, filePath);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+export function normalizeExtensions(extensions: string[]): string[] {
+	const normalized = new Set<string>();
+
+	for (const ext of extensions) {
+		if (!EXTENSION_PATTERN.test(ext)) {
+			throw new Error(
+				`Invalid module extension "${ext}". Use simple extensions like ".ts", ".js", or ".mjs".`,
+			);
+		}
+
+		normalized.add(ext);
+	}
+
+	if (normalized.size === 0) {
+		throw new Error("At least one module extension is required.");
+	}
+
+	return [...normalized].sort();
+}
+
+export async function discoverModuleFiles(options: {
+	dir: string;
+	extensions: string[];
+}): Promise<DiscoveredModuleFiles> {
+	const rootDir = await realpath(resolveDir(options.dir));
+	const rootStats = await lstat(rootDir);
+
+	if (!rootStats.isDirectory()) {
+		throw new Error(`Module directory is not a directory: ${rootDir}`);
+	}
+
+	const extensions = normalizeExtensions(options.extensions);
+	const files = new Set<string>();
+
+	for (const ext of extensions) {
+		const pattern = path.join(rootDir, `**/*${ext}`);
+
+		for await (const filePath of new Bun.Glob(pattern).scan()) {
+			if (filePath.endsWith(".d.ts")) continue;
+
+			const realFilePath = await realpath(filePath);
+			if (!isInsideDir(rootDir, realFilePath)) continue;
+
+			const stats = await lstat(realFilePath);
+			if (!stats.isFile()) continue;
+
+			files.add(realFilePath);
+		}
+	}
+
+	return {
+		rootDir,
+		files: [...files].sort((a, b) => a.localeCompare(b)),
+	};
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+export * from "./handler/command";
+export * from "./handler/context";
+export * from "./handler/events";
+export * from "./handler/manager";
+export * from "./handler/tasks";
+export type {
+	CommandContext,
+	CommandMeta,
+	ComponentHandler,
+	SlashCommand,
+	SlashCommandData,
+} from "./handler/@types/command";
+export type {
+	ContextMenuCommand,
+	ContextMenuMeta,
+	MessageContextMenuCommand,
+	UserContextMenuCommand,
+} from "./handler/@types/contextMenu";
+export {
+	defineMessageContextMenu,
+	defineUserContextMenu,
+} from "./handler/@types/contextMenu";
+export type {
+	EventListenerModule,
+	EventName,
+} from "./handler/@types/event";
+export { defineEvent } from "./handler/@types/event";
+export type {
+	Precondition,
+	PreconditionContext,
+	PreconditionResult,
+} from "./handler/@types/precondition";
+export type {
+	LoadedTask,
+	TaskContext,
+	TaskModule,
+} from "./handler/@types/task";
+export { defineTask } from "./handler/@types/task";
+export type { ClientClass, HandlerClient } from "./structure/Client";

package/src/structure/Client.ts

@@ -0,0 +1,8 @@
+export type HandlerClient = {
+	on: (eventName: any, listener: (...args: any[]) => unknown) => unknown;
+	once: (eventName: any, listener: (...args: any[]) => unknown) => unknown;
+	off: (eventName: any, listener: (...args: any[]) => unknown) => unknown;
+	db?: any;
+};
+
+export type ClientClass = HandlerClient;

package/src/utils/index.ts

@@ -0,0 +1 @@
+export * from "./logger";

package/src/utils/logger.ts

@@ -0,0 +1,63 @@
+type LogContext =
+	| Record<string, string | number | boolean | null | undefined>
+	| undefined;
+
+export type Logger = {
+	info: (message: string, context?: LogContext) => void;
+	warn: (message: string, context?: LogContext) => void;
+	error: (message: string, error?: unknown, context?: LogContext) => void;
+	debug: (message: string, context?: LogContext) => void;
+};
+
+function timestamp(): string {
+	return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function formatContext(context: LogContext): string {
+	if (!context) return "";
+
+	const entries = Object.entries(context).filter(([, value]) => value !== undefined);
+	if (entries.length === 0) return "";
+
+	return ` ${entries.map(([key, value]) => `${key}=${String(value)}`).join(" ")}`;
+}
+
+function normalizeError(error: unknown): { message: string; stack?: string } {
+	if (error instanceof Error) {
+		return { message: error.message, stack: error.stack };
+	}
+
+	try {
+		return { message: JSON.stringify(error) };
+	} catch {
+		return { message: String(error) };
+	}
+}
+
+const debugEnabled = (): boolean =>
+	String(Bun.env.LOG_LEVEL ?? "").toLowerCase() === "debug";
+
+export const logger: Logger = {
+	info(message, context) {
+		console.log(`${timestamp()} [INFO] ${message}${formatContext(context)}`);
+	},
+
+	warn(message, context) {
+		console.warn(`${timestamp()} [WARN] ${message}${formatContext(context)}`);
+	},
+
+	error(message, error, context) {
+		console.error(`${timestamp()} [ERROR] ${message}${formatContext(context)}`);
+
+		if (error === undefined) return;
+
+		const normalized = normalizeError(error);
+		console.error(normalized.message);
+		if (normalized.stack) console.error(normalized.stack);
+	},
+
+	debug(message, context) {
+		if (!debugEnabled()) return;
+		console.log(`${timestamp()} [DEBUG] ${message}${formatContext(context)}`);
+	},
+};