@gencow/core 0.1.0

package/src/crons.ts

@@ -0,0 +1,131 @@
+/**
+ * packages/core/src/crons.ts
+ *
+ * 선언적 Cron Jobs — Convex cronJobs() 패턴
+ *
+ * gencow/crons.ts 파일에 선언하면 서버 시작 시 자동 등록됩니다.
+ *
+ * @example
+ * // gencow/crons.ts
+ * import { cronJobs } from "@gencow/core";
+ *
+ * const crons = cronJobs();
+ * crons.interval("sync-metrics", { minutes: 15 }, "metrics.collect");
+ * crons.daily("cleanup", { hour: 2 }, "admin.cleanup");
+ * crons.cron("custom", "0 * * * *", "hourly.task");
+ * export default crons;
+ */
+
+// ─── 타입 ───────────────────────────────────────────────
+
+export interface CronJobDef {
+    /** 크론 잡 이름 */
+    name: string;
+    /** cron 표현식 (예: "0 2 * * *") */
+    pattern: string;
+    /** 실행할 액션 또는 핸들러 */
+    action: string | (() => Promise<void>);
+}
+
+export interface IntervalOptions {
+    /** 분 단위 */
+    minutes?: number;
+    /** 시간 단위 */
+    hours?: number;
+    /** 초 단위 */
+    seconds?: number;
+}
+
+export interface DailyOptions {
+    /** 실행 시각 (0-23, 로컬 시간) */
+    hour: number;
+    /** 분 (0-59, 기본 0) */
+    minute?: number;
+}
+
+export interface WeeklyOptions {
+    /** 요일 (0=일, 1=월, ..., 6=토) */
+    dayOfWeek: number;
+    /** 시각 (0-23) */
+    hour: number;
+    /** 분 (0-59, 기본 0) */
+    minute?: number;
+}
+
+export interface CronJobsBuilder {
+    /** 일정 간격으로 실행 */
+    interval(name: string, options: IntervalOptions, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** 매일 특정 시각에 실행 */
+    daily(name: string, options: DailyOptions, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** 매주 특정 요일/시각에 실행 */
+    weekly(name: string, options: WeeklyOptions, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** cron 표현식으로 직접 지정 */
+    cron(name: string, pattern: string, action: string | (() => Promise<void>)): CronJobsBuilder;
+    /** 등록된 크론 잡 목록 (서버 내부에서 사용) */
+    getJobs(): CronJobDef[];
+}
+
+// ─── 빌더 구현 ──────────────────────────────────────────
+
+/**
+ * 선언적 크론 잡 빌더
+ *
+ * @example
+ * const crons = cronJobs();
+ * crons.interval("sync", { minutes: 15 }, "metrics.collect");
+ * crons.daily("report", { hour: 9 }, "reports.generate");
+ * crons.cron("custom", "0 30 * * *", "custom.handler");
+ * export default crons;
+ */
+export function cronJobs(): CronJobsBuilder {
+    const jobs: CronJobDef[] = [];
+
+    const builder: CronJobsBuilder = {
+        interval(name, options, action) {
+            const pattern = intervalToPattern(options);
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+
+        daily(name, options, action) {
+            const minute = options.minute ?? 0;
+            const pattern = `${minute} ${options.hour} * * *`;
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+
+        weekly(name, options, action) {
+            const minute = options.minute ?? 0;
+            const pattern = `${minute} ${options.hour} * * ${options.dayOfWeek}`;
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+
+        cron(name, pattern, action) {
+            jobs.push({ name, pattern, action });
+            return builder;
+        },
+
+        getJobs() {
+            return [...jobs];
+        },
+    };
+
+    return builder;
+}
+
+// ─── 유틸리티 ───────────────────────────────────────────
+
+function intervalToPattern(options: IntervalOptions): string {
+    if (options.seconds) {
+        // node-cron은 초 단위 지원: "*/N * * * * *"
+        return `*/${options.seconds} * * * * *`;
+    }
+    if (options.minutes) {
+        return `*/${options.minutes} * * * *`;
+    }
+    if (options.hours) {
+        return `0 */${options.hours} * * *`;
+    }
+    throw new Error("interval: minutes, hours, 또는 seconds 중 하나를 지정하세요");
+}

package/src/db.ts

@@ -0,0 +1,18 @@
+/**
+ * @deprecated — 레거시 싱글톤 DB 인스턴스.
+ * 새 코드에서는 ctx.db를 사용하세요.
+ * 서버의 createDatabase() (database.ts)가 실제 DB 연결을 관리합니다.
+ */
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+
+let pgliteInstance: PGlite | null = null;
+
+/** @deprecated Use ctx.db instead */
+export async function createDb(dataDir: string = "./data") {
+    if (!pgliteInstance) {
+        pgliteInstance = new PGlite(dataDir);
+    }
+    const db = drizzle(pgliteInstance);
+    return { db, client: pgliteInstance };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Platform Core — Convex-like Backend Framework
+ *
+ * Provides: query, mutation, storage, scheduler, auth
+ * All with Convex-compatible DX patterns.
+ */
+
+export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx } from "./reactive";
+export { query, mutation, invalidateQueries, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations } from "./reactive";
+export type { Storage } from "./storage";
+export { createScheduler, getSchedulerInfo } from "./scheduler";
+export type { Scheduler } from "./scheduler";
+export { v, parseArgs, GencowValidationError } from "./v";
+export type { Validator, Infer, InferArgs } from "./v";
+export { withRetry } from "./retry";
+export type { RetryOptions } from "./retry";
+export { cronJobs } from "./crons";
+export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons";
+
+

package/src/reactive.ts

@@ -0,0 +1,280 @@
+import type { WSContext } from "hono/ws";
+import type { Storage } from "./storage";
+import type { Scheduler } from "./scheduler";
+import { type Validator, type InferArgs } from "./v";
+
+// ─── GencowCtx — 사용자 함수에 주입되는 컨텍스트 ──────────
+
+export interface UserIdentity {
+    id: string;
+    email: string;
+    name?: string;
+}
+
+export interface AuthCtx {
+    /** 현재 유저 반환 (비로그인 시 null) — Convex의 ctx.auth.getUserIdentity() */
+    getUserIdentity(): UserIdentity | null;
+    /** 현재 유저 반환 (비로그인 시 401 throw) */
+    requireAuth(): UserIdentity;
+}
+
+/**
+ * mutation handler 내에서 구독자들에게 데이터를 즉시 push합니다.
+ * 클라이언트는 이 데이터를 받아 re-fetch 없이 state를 업데이트합니다.
+ */
+export interface RealtimeCtx {
+    /**
+     * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
+     * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
+     *
+     * @example
+     *   const freshList = await ctx.db.select().from(tasks);
+     *   ctx.realtime.emit("tasks.list", freshList);
+     */
+    emit(queryKey: string, data: unknown): void;
+}
+
+/**
+ * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
+ * Convex의 ctx 패턴과 동일하게, 이 객체를 통해서만 DB/Storage/Auth에 접근 가능.
+ * fs, child_process 등 원시 Node.js API는 노출되지 않음.
+ */
+export interface GencowCtx {
+    /** Drizzle DB 인스턴스 — ctx.db.select().from(table) */
+    db: any; // typed per-app via generic
+    /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
+    auth: AuthCtx;
+    /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
+    storage: Storage;
+    /** 스케줄러 — ctx.scheduler.runAfter(), ctx.scheduler.cron() */
+    scheduler: Scheduler;
+    /** 실시간 push — ctx.realtime.emit(queryKey, data) */
+    realtime: RealtimeCtx;
+    /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
+    retry: <T>(fn: () => Promise<T>, options?: import("./retry").RetryOptions) => Promise<T>;
+}
+
+// ─── Types ──────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
+
+export interface QueryDef<TSchema = any, TReturn = any> {
+    key: string;
+    handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+    argsSchema?: TSchema;
+    _args?: InferArgs<TSchema>;
+    _return?: TReturn;
+}
+
+export interface MutationDef<TSchema = any, TReturn = any> {
+    invalidates: string[];
+    handler: MutationHandler<InferArgs<TSchema>, TReturn>;
+    argsSchema?: TSchema;
+    _args?: InferArgs<TSchema>;
+    _return?: TReturn;
+}
+
+// ─── Registry ───────────────────────────────────────────
+
+const queryRegistry = new Map<string, QueryDef<any, any>>();
+const mutationRegistry: (MutationDef<any, any> & { name: string })[] = [];
+const subscribers = new Map<string, Set<WSContext>>();
+
+/**
+ * Every WebSocket client that ever establishes a connection is tracked here.
+ * This allows broadcasting invalidation events to clients that never subscribed
+ * to a specific query (e.g. the admin dashboard's raw WebSocket connection).
+ */
+const connectedClients = new Set<WSContext>();
+
+// ─── Public API (Convex-style) ──────────────────────────
+
+export function query<TSchema = any, TReturn = any>(
+    key: string,
+    handlerOrDef: QueryHandler<InferArgs<TSchema>, TReturn> | { args?: TSchema; handler: QueryHandler<InferArgs<TSchema>, TReturn> }
+): QueryDef<TSchema, TReturn> {
+    let handler: QueryHandler<InferArgs<TSchema>, TReturn>;
+    let argsSchema: TSchema | undefined;
+
+    if (typeof handlerOrDef === "function") {
+        handler = handlerOrDef;
+    } else {
+        handler = handlerOrDef.handler;
+        argsSchema = handlerOrDef.args;
+    }
+
+    const def: QueryDef<TSchema, TReturn> = { key, handler, argsSchema };
+    queryRegistry.set(key, def);
+    return def;
+}
+
+let mutationCounter = 0;
+
+export function mutation<TSchema = any, TReturn = any>(
+    invalidatesOrDef: string[] | { name?: string; args?: TSchema; invalidates: string[]; handler: MutationHandler<InferArgs<TSchema>, TReturn> },
+    handler?: MutationHandler<InferArgs<TSchema>, TReturn>,
+    name?: string
+): MutationDef<TSchema, TReturn> {
+    let invalidates: string[];
+    let argsSchema: TSchema | undefined;
+    let actualHandler: MutationHandler<InferArgs<TSchema>, TReturn>;
+    let mutName: string;
+
+    if (Array.isArray(invalidatesOrDef)) {
+        // Legacy style: mutation([...], handler, "name")
+        invalidates = invalidatesOrDef;
+        actualHandler = handler!;
+        mutName = name || `mutation_${++mutationCounter}`;
+    } else {
+        // New object style: mutation({ name?, invalidates, args?, handler })
+        invalidates = invalidatesOrDef.invalidates;
+        actualHandler = invalidatesOrDef.handler;
+        argsSchema = invalidatesOrDef.args;
+        mutName = invalidatesOrDef.name || name || `mutation_${++mutationCounter}`;
+    }
+    const def: MutationDef<TSchema, TReturn> & { name: string } = {
+        name: mutName,
+        invalidates,
+        handler: actualHandler,
+        argsSchema
+    };
+    mutationRegistry.push(def);
+    return def;
+}
+
+// ─── WebSocket subscription management ──────────────────
+
+export function subscribe(queryKey: string, ws: WSContext) {
+    connectedClients.add(ws);
+    if (!subscribers.has(queryKey)) {
+        subscribers.set(queryKey, new Set());
+    }
+    subscribers.get(queryKey)!.add(ws);
+}
+
+export function unsubscribe(ws: WSContext) {
+    connectedClients.delete(ws);
+    for (const clients of subscribers.values()) {
+        clients.delete(ws);
+    }
+}
+
+/** Register a raw WS connection without any query subscription (e.g. admin dashboard) */
+export function registerClient(ws: WSContext) {
+    connectedClients.add(ws);
+}
+
+export function deregisterClient(ws: WSContext) {
+    connectedClients.delete(ws);
+    for (const clients of subscribers.values()) {
+        clients.delete(ws);
+    }
+}
+
+/**
+ * After a mutation, re-run invalidated queries and push results
+ * to all subscribers — Convex의 자동 reactive 업데이트 재현
+ */
+/**
+ * mutation 실행 시점에 생성되는 RealtimeCtx.
+ * emit() 호출 시 해당 queryKey를 구독 중인 WebSocket 클라이언트들에게
+ * data를 즉시 push합니다.
+ *
+ * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
+ * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
+ *
+ * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
+ */
+export function buildRealtimeCtx(): RealtimeCtx {
+    const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
+
+    return {
+        emit(queryKey: string, data: unknown) {
+            // 기존 pending timer가 있으면 취소 (debounce)
+            const existing = pendingEmits.get(queryKey);
+            if (existing) clearTimeout(existing.timer);
+
+            const timer = setTimeout(() => {
+                pendingEmits.delete(queryKey);
+                const clients = subscribers.get(queryKey);
+                if (!clients || clients.size === 0) return;
+
+                const message = JSON.stringify({
+                    type: "query:updated",
+                    query: queryKey,
+                    data,
+                });
+                for (const ws of clients) {
+                    try { ws.send(message); } catch { clients.delete(ws); }
+                }
+            }, 50); // 50ms batch window
+
+            pendingEmits.set(queryKey, { data, timer });
+        }
+    };
+}
+
+/**
+ * mutation이 끝난 후 호출되는 legacy fallback.
+ * `ctx.realtime.emit()`을 사용하는 새 mutation에서는 빈 배열([])을 전달하면 됩니다.
+ *
+ * invalidate 신호만 broadcast하여 클라이언트가 re-fetch 여부를 결정하게 합니다.
+ * (서버에서 쿼리를 재실행하지 않으므로 DB 부하 없음)
+ *
+ * @deprecated ctx.realtime.emit() 사용 권장
+ */
+export async function invalidateQueries(
+    queryKeys: string[],
+    ctx: GencowCtx
+): Promise<void> {
+    if (queryKeys.length === 0) return; // emit() 방식에서는 no-op
+
+    // invalidate 신호만 broadcast (re-fetch는 클라이언트 결정에 맡김)
+    const invalidateMsg = JSON.stringify({ type: "invalidate", queries: queryKeys });
+    for (const ws of connectedClients) {
+        try { ws.send(invalidateMsg); } catch { connectedClients.delete(ws); }
+    }
+}
+
+
+// ─── WebSocket message handler ──────────────────────────
+
+export function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer) {
+    try {
+        const msg =
+            typeof raw === "string" ? JSON.parse(raw) : JSON.parse(raw.toString());
+
+        if (msg.type === "subscribe" && msg.query) {
+            subscribe(msg.query, ws);
+            ws.send(
+                JSON.stringify({ type: "subscribed", query: msg.query })
+            );
+        }
+
+        if (msg.type === "unsubscribe" && msg.query) {
+            const clients = subscribers.get(msg.query);
+            if (clients) clients.delete(ws);
+        }
+    } catch {
+        // ignore malformed messages
+    }
+}
+
+export function getQueryHandler(key: string): QueryHandler | undefined {
+    return queryRegistry.get(key)?.handler;
+}
+
+export function getQueryDef(key: string): QueryDef | undefined {
+    return queryRegistry.get(key);
+}
+
+export function getRegisteredQueries(): string[] {
+    return Array.from(queryRegistry.keys());
+}
+
+export function getRegisteredMutations(): (MutationDef & { name: string })[] {
+    return [...mutationRegistry];
+}

package/src/retry.ts

@@ -0,0 +1,112 @@
+/**
+ * packages/core/src/retry.ts
+ *
+ * Retry 유틸리티 — exponential backoff + jitter
+ *
+ * 외부 API(LLM, 결제, 이메일 등) 호출 실패 시 자동 재시도.
+ * ctx.retry() 또는 독립 함수 withRetry()로 사용 가능.
+ *
+ * @example
+ * // 독립 함수
+ * import { withRetry } from "@gencow/core";
+ * const result = await withRetry(() => fetch("https://api.example.com"), {
+ *     maxAttempts: 5,
+ *     initialBackoffMs: 500,
+ * });
+ *
+ * // ctx에 내장
+ * export const charge = mutation({
+ *     handler: async (ctx, args) => {
+ *         const result = await ctx.retry(
+ *             () => stripe.charges.create({ amount: args.amount }),
+ *             { maxAttempts: 3, initialBackoffMs: 500 },
+ *         );
+ *         return result;
+ *     },
+ * });
+ */
+
+// ─── 타입 ───────────────────────────────────────────────
+
+export interface RetryOptions {
+    /** 최대 시도 횟수 (기본 3) */
+    maxAttempts?: number;
+    /** 첫 번째 재시도 대기 시간 (ms, 기본 1000) */
+    initialBackoffMs?: number;
+    /** backoff 배수 (기본 2 → 1s, 2s, 4s, 8s, ...) */
+    base?: number;
+    /** 최대 대기 시간 (ms, 기본 30000) */
+    maxBackoffMs?: number;
+    /** 재시도할 에러인지 판단 (기본: 모든 에러 재시도) */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** 재시도 시 호출되는 콜백 (로깅용) */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+
+// ─── 기본값 ─────────────────────────────────────────────
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_BACKOFF_MS = 1000;
+const DEFAULT_BASE = 2;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+const JITTER_MIN = 0.75;
+const JITTER_MAX = 1.25;
+
+// ─── 핵심 함수 ──────────────────────────────────────────
+
+/**
+ * 재시도 가능한 비동기 함수 실행
+ *
+ * Exponential backoff + jitter로 재시도.
+ * delay = min(initialBackoffMs × base^attempt × jitter, maxBackoffMs)
+ */
+export async function withRetry<T>(
+    fn: () => Promise<T>,
+    options: RetryOptions = {},
+): Promise<T> {
+    const {
+        maxAttempts = DEFAULT_MAX_ATTEMPTS,
+        initialBackoffMs = DEFAULT_INITIAL_BACKOFF_MS,
+        base = DEFAULT_BASE,
+        maxBackoffMs = DEFAULT_MAX_BACKOFF_MS,
+        shouldRetry,
+        onRetry,
+    } = options;
+
+    if (maxAttempts < 1) {
+        throw new Error(`withRetry: maxAttempts must be >= 1, got ${maxAttempts}`);
+    }
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        } catch (error: unknown) {
+            const isLastAttempt = attempt === maxAttempts - 1;
+
+            // 마지막 시도면 에러 throw
+            if (isLastAttempt) throw error;
+
+            // shouldRetry가 있으면 판단
+            if (shouldRetry && !shouldRetry(error, attempt)) throw error;
+
+            // 딜레이 계산: exponential backoff + jitter
+            const jitter = JITTER_MIN + Math.random() * (JITTER_MAX - JITTER_MIN);
+            const rawDelay = initialBackoffMs * Math.pow(base, attempt) * jitter;
+            const delay = Math.min(rawDelay, maxBackoffMs);
+
+            // 콜백 호출
+            if (onRetry) onRetry(error, attempt + 1, delay);
+
+            await sleep(delay);
+        }
+    }
+
+    // TypeScript를 위한 unreachable — 실제로 여기에 도달하지 않음
+    throw new Error("withRetry: unreachable");
+}
+
+// ─── 내부 유틸리티 ──────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/scheduler.ts

@@ -0,0 +1,129 @@
+import * as cron from "node-cron";
+
+// ─── Types ──────────────────────────────────────────────
+
+type ActionHandler = (args: any) => Promise<any>;
+
+export interface Scheduler {
+    /** Schedule a function to run after a delay — Convex의 ctx.scheduler.runAfter() */
+    runAfter(ms: number, action: string, args?: any): string;
+    /** Schedule a function at a specific time — Convex의 ctx.scheduler.runAt() */
+    runAt(timestamp: number | Date, action: string, args?: any): string;
+    /** Cancel a scheduled function */
+    cancel(jobId: string): boolean;
+    /** Register a cron job — Convex의 cronJobs() */
+    cron(name: string, pattern: string, handler: () => Promise<void>): void;
+    /** Register an action handler */
+    registerAction(name: string, handler: ActionHandler): void;
+}
+
+// ─── Implementation ─────────────────────────────────────
+
+/**
+ * Create a scheduler instance — Convex scheduler 패턴 재현
+ *
+ * @example
+ * const scheduler = createScheduler();
+ *
+ * // Register actions
+ * scheduler.registerAction('emails.send', async (args) => { ... });
+ *
+ * // Schedule (Convex-style)
+ * scheduler.runAfter(5 * 60 * 1000, 'emails.send', { to: 'user@test.com' });
+ *
+ * // Cron (Convex-style)
+ * scheduler.cron('daily-cleanup', '0 2 * * *', async () => { ... });
+ */
+// Module-level state for dashboard introspection
+const _cronInfo: { name: string; pattern: string; registeredAt: string }[] = [];
+const _pendingJobs: { id: string; action: string; scheduledAt: string }[] = [];
+
+export function getSchedulerInfo() {
+    return {
+        crons: _cronInfo,
+        pendingJobs: _pendingJobs,
+    };
+}
+
+export function createScheduler(): Scheduler {
+    const timers = new Map<string, NodeJS.Timeout>();
+    const cronJobs = new Map<string, cron.ScheduledTask>();
+    const actions = new Map<string, ActionHandler>();
+
+    let jobCounter = 0;
+
+    function generateId(): string {
+        return `job_${++jobCounter}_${Date.now()}`;
+    }
+
+    async function executeAction(action: string, args: any) {
+        const handler = actions.get(action);
+        if (!handler) {
+            console.error(`[scheduler] Action "${action}" not registered`);
+            return;
+        }
+        try {
+            await handler(args);
+            console.log(`[scheduler] Action "${action}" completed`);
+        } catch (error) {
+            console.error(`[scheduler] Action "${action}" failed:`, error);
+        }
+    }
+
+    return {
+        runAfter(ms: number, action: string, args?: any): string {
+            const id = generateId();
+            _pendingJobs.push({ id, action, scheduledAt: new Date().toISOString() });
+            const timer = setTimeout(async () => {
+                await executeAction(action, args);
+                timers.delete(id);
+                const idx = _pendingJobs.findIndex((j) => j.id === id);
+                if (idx >= 0) _pendingJobs.splice(idx, 1);
+            }, ms);
+            timers.set(id, timer);
+            console.log(
+                `[scheduler] Scheduled "${action}" to run after ${ms}ms (id: ${id})`
+            );
+            return id;
+        },
+
+        runAt(timestamp: number | Date, action: string, args?: any): string {
+            const target =
+                timestamp instanceof Date ? timestamp.getTime() : timestamp;
+            const ms = Math.max(0, target - Date.now());
+            return this.runAfter(ms, action, args);
+        },
+
+        cancel(jobId: string): boolean {
+            const timer = timers.get(jobId);
+            if (timer) {
+                clearTimeout(timer);
+                timers.delete(jobId);
+                console.log(`[scheduler] Cancelled job ${jobId}`);
+                return true;
+            }
+            return false;
+        },
+
+        cron(name: string, pattern: string, handler: () => Promise<void>): void {
+            if (cronJobs.has(name)) {
+                cronJobs.get(name)!.stop();
+            }
+            const task = cron.schedule(pattern, async () => {
+                console.log(`[scheduler] Cron "${name}" triggered`);
+                try {
+                    await handler();
+                } catch (error) {
+                    console.error(`[scheduler] Cron "${name}" failed:`, error);
+                }
+            });
+            cronJobs.set(name, task);
+            _cronInfo.push({ name, pattern, registeredAt: new Date().toISOString() });
+            console.log(`[scheduler] Registered cron "${name}" with pattern "${pattern}"`);
+        },
+
+        registerAction(name: string, handler: ActionHandler): void {
+            actions.set(name, handler);
+        },
+    };
+}