fastscript 1.0.0 → 2.0.0

package/node_modules/@fastscript/core-private/src/oauth-providers.mjs

@@ -0,0 +1,103 @@
+import { buildOAuthAuthorizeUrl, createOAuthState } from "./auth-flows.mjs";
+
+const PROVIDERS = {
+  github: {
+    name: "GitHub",
+    authorizeUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    userUrl: "https://api.github.com/user",
+    scope: "read:user user:email",
+  },
+  google: {
+    name: "Google",
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    userUrl: "https://www.googleapis.com/oauth2/v3/userinfo",
+    scope: "openid email profile",
+  },
+  microsoft: {
+    name: "Microsoft",
+    authorizeUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    userUrl: "https://graph.microsoft.com/v1.0/me",
+    scope: "openid profile email User.Read",
+  },
+};
+
+export function listAuthProviders() {
+  return Object.keys(PROVIDERS);
+}
+
+export function getAuthProvider(name) {
+  const key = String(name || "").toLowerCase();
+  const provider = PROVIDERS[key];
+  if (!provider) {
+    const error = new Error(`Unknown OAuth provider: ${name}`);
+    error.status = 400;
+    throw error;
+  }
+  return { id: key, ...provider };
+}
+
+export function createOAuthAdapter(name, {
+  clientId = process.env[`${String(name || "").toUpperCase()}_CLIENT_ID`],
+  clientSecret = process.env[`${String(name || "").toUpperCase()}_CLIENT_SECRET`],
+  redirectUri = process.env[`${String(name || "").toUpperCase()}_REDIRECT_URI`],
+} = {}) {
+  const provider = getAuthProvider(name);
+  return {
+    ...provider,
+    clientId,
+    clientSecret,
+    redirectUri,
+    authorizeUrl({ state = createOAuthState(), scope = provider.scope } = {}) {
+      return {
+        state,
+        url: buildOAuthAuthorizeUrl({
+          authorizeUrl: provider.authorizeUrl,
+          clientId,
+          redirectUri,
+          scope,
+          state,
+        }),
+      };
+    },
+    async exchangeCode(code) {
+      const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uri: redirectUri,
+      });
+      const response = await fetch(provider.tokenUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          accept: "application/json",
+        },
+        body,
+      });
+      if (!response.ok) {
+        const error = new Error(`OAuth token exchange failed (${response.status})`);
+        error.status = 502;
+        throw error;
+      }
+      return response.json();
+    },
+    async fetchUser(accessToken) {
+      const response = await fetch(provider.userUrl, {
+        headers: {
+          authorization: `Bearer ${accessToken}`,
+          accept: "application/json",
+        },
+      });
+      if (!response.ok) {
+        const error = new Error(`OAuth user fetch failed (${response.status})`);
+        error.status = 502;
+        throw error;
+      }
+      return response.json();
+    },
+  };
+}

package/node_modules/@fastscript/core-private/src/observability.mjs

@@ -0,0 +1,21 @@
+export function createTracer({ service = "fastscript" } = {}) {
+  return {
+    span(name, attrs = {}) {
+      const start = Date.now();
+      return {
+        end(extra = {}) {
+          console.log(JSON.stringify({ type: "trace", service, name, ms: Date.now() - start, ...attrs, ...extra }));
+        },
+      };
+    },
+  };
+}
+
+export async function createOtelExporter() {
+  try {
+    const api = await import("@opentelemetry/api");
+    return api.trace.getTracer("fastscript");
+  } catch {
+    return null;
+  }
+}

package/node_modules/@fastscript/core-private/src/plugins.mjs

@@ -0,0 +1,194 @@
+import { existsSync } from "node:fs";
+import { extname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { importSourceModule } from "./module-loader.mjs";
+
+export const PLUGIN_API_VERSION = 1;
+const DEFAULT_PLUGIN_TIMEOUT_MS = Number(process.env.PLUGIN_TIMEOUT_MS || 2500);
+
+const CONFIG_CANDIDATES = [
+  "fastscript.plugins.fs",
+  "fastscript.plugins.js",
+  "fastscript.plugins.mjs",
+  "fastscript.plugins.cjs",
+  "app/plugins.fs",
+  "app/plugins.js",
+  "app/plugins.mjs",
+  "app/plugins.cjs",
+];
+
+function asArray(value) {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function createNullLogger() {
+  return {
+    info() {},
+    warn() {},
+    error() {},
+  };
+}
+
+function withTimeout(task, ms, label) {
+  if (!Number.isFinite(ms) || ms <= 0) return task;
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error(`Plugin hook timeout (${ms}ms): ${label}`);
+      error.code = "PLUGIN_HOOK_TIMEOUT";
+      reject(error);
+    }, ms);
+  });
+  return Promise.race([task.finally(() => clearTimeout(timer)), timeout]);
+}
+
+async function importPluginModule(file) {
+  const abs = resolve(file);
+  const ext = extname(abs).toLowerCase();
+  if (ext === ".fs") return importSourceModule(abs, { platform: "node" });
+  return import(`${pathToFileURL(abs).href}?t=${Date.now()}`);
+}
+
+function normalizePluginEntries(mod) {
+  const entries = [];
+  entries.push(...asArray(mod?.plugins));
+  entries.push(...asArray(mod?.default));
+  return entries;
+}
+
+function normalizePlugin(raw, fallbackName) {
+  if (!raw) return null;
+  if (typeof raw === "function") {
+    return { name: fallbackName, apiVersion: PLUGIN_API_VERSION, setup: raw };
+  }
+  if (typeof raw !== "object") return null;
+  const setup = typeof raw.setup === "function" ? raw.setup : null;
+  const plugin = {
+    name: raw.name || fallbackName,
+    apiVersion: Number.isInteger(raw.apiVersion) ? raw.apiVersion : PLUGIN_API_VERSION,
+    setup,
+  };
+  if (typeof raw.middleware === "function") plugin.middleware = raw.middleware;
+  if (typeof raw.onBuildStart === "function") plugin.onBuildStart = raw.onBuildStart;
+  if (typeof raw.onBuildEnd === "function") plugin.onBuildEnd = raw.onBuildEnd;
+  if (typeof raw.onRequestStart === "function") plugin.onRequestStart = raw.onRequestStart;
+  if (typeof raw.onRequestEnd === "function") plugin.onRequestEnd = raw.onRequestEnd;
+  return plugin;
+}
+
+function createRegistry() {
+  return {
+    middleware: [],
+    onBuildStart: [],
+    onBuildEnd: [],
+    onRequestStart: [],
+    onRequestEnd: [],
+  };
+}
+
+async function runHookList(hooks, ctx, logger, stage) {
+  for (const hook of hooks) {
+    const label = `${hook.plugin}:${stage}`;
+    try {
+      await withTimeout(Promise.resolve(hook.fn(ctx)), hook.timeoutMs ?? DEFAULT_PLUGIN_TIMEOUT_MS, label);
+    } catch (error) {
+      logger.warn("plugin_hook_failed", {
+        plugin: hook.plugin,
+        stage,
+        error: error?.message || String(error),
+      });
+    }
+  }
+}
+
+function createHookApi(registry, pluginName) {
+  return {
+    middleware(fn, opts = {}) {
+      if (typeof fn !== "function") return;
+      registry.middleware.push({ plugin: pluginName, fn, timeoutMs: opts.timeoutMs });
+    },
+    onBuildStart(fn, opts = {}) {
+      if (typeof fn !== "function") return;
+      registry.onBuildStart.push({ plugin: pluginName, fn, timeoutMs: opts.timeoutMs });
+    },
+    onBuildEnd(fn, opts = {}) {
+      if (typeof fn !== "function") return;
+      registry.onBuildEnd.push({ plugin: pluginName, fn, timeoutMs: opts.timeoutMs });
+    },
+    onRequestStart(fn, opts = {}) {
+      if (typeof fn !== "function") return;
+      registry.onRequestStart.push({ plugin: pluginName, fn, timeoutMs: opts.timeoutMs });
+    },
+    onRequestEnd(fn, opts = {}) {
+      if (typeof fn !== "function") return;
+      registry.onRequestEnd.push({ plugin: pluginName, fn, timeoutMs: opts.timeoutMs });
+    },
+  };
+}
+
+function configFiles(root) {
+  return CONFIG_CANDIDATES.map((file) => join(root, file)).filter((p) => existsSync(p));
+}
+
+export async function createPluginRuntime({ root = process.cwd(), logger = createNullLogger() } = {}) {
+  const files = configFiles(root);
+  const registry = createRegistry();
+  const loaded = [];
+
+  for (const file of files) {
+    let mod;
+    try {
+      mod = await importPluginModule(file);
+    } catch (error) {
+      logger.warn("plugin_module_load_failed", { file, error: error?.message || String(error) });
+      continue;
+    }
+    const rawEntries = normalizePluginEntries(mod);
+    rawEntries.forEach((raw, idx) => {
+      const plugin = normalizePlugin(raw, `${file}#${idx + 1}`);
+      if (!plugin) return;
+      if (plugin.apiVersion !== PLUGIN_API_VERSION) {
+        logger.warn("plugin_api_version_mismatch", {
+          plugin: plugin.name,
+          expected: PLUGIN_API_VERSION,
+          received: plugin.apiVersion,
+        });
+        return;
+      }
+
+      const hooks = createHookApi(registry, plugin.name);
+      try {
+        if (plugin.middleware) hooks.middleware(plugin.middleware);
+        if (plugin.onBuildStart) hooks.onBuildStart(plugin.onBuildStart);
+        if (plugin.onBuildEnd) hooks.onBuildEnd(plugin.onBuildEnd);
+        if (plugin.onRequestStart) hooks.onRequestStart(plugin.onRequestStart);
+        if (plugin.onRequestEnd) hooks.onRequestEnd(plugin.onRequestEnd);
+        if (plugin.setup) plugin.setup({ hooks, apiVersion: PLUGIN_API_VERSION });
+        loaded.push({ name: plugin.name, file });
+      } catch (error) {
+        logger.warn("plugin_setup_failed", { plugin: plugin.name, file, error: error?.message || String(error) });
+      }
+    });
+  }
+
+  return {
+    apiVersion: PLUGIN_API_VERSION,
+    loaded,
+    middleware() {
+      return registry.middleware.map((row) => row.fn);
+    },
+    async onBuildStart(ctx = {}) {
+      await runHookList(registry.onBuildStart, ctx, logger, "onBuildStart");
+    },
+    async onBuildEnd(ctx = {}) {
+      await runHookList(registry.onBuildEnd, ctx, logger, "onBuildEnd");
+    },
+    async onRequestStart(ctx = {}) {
+      await runHookList(registry.onRequestStart, ctx, logger, "onRequestStart");
+    },
+    async onRequestEnd(ctx = {}) {
+      await runHookList(registry.onRequestEnd, ctx, logger, "onRequestEnd");
+    },
+  };
+}

package/node_modules/@fastscript/core-private/src/retention.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export function applyJsonArrayRetention(path, { timestampField = "ts", maxAgeMs = 1000 * 60 * 60 * 24 * 30 } = {}) {
+  const rows = readJson(path, []);
+  if (!Array.isArray(rows)) return { kept: 0, removed: 0 };
+  const cutoff = Date.now() - maxAgeMs;
+  const kept = rows.filter((row) => {
+    const raw = row?.[timestampField] || row?.failedAt || row?.createdAt || null;
+    const n = typeof raw === "number" ? raw : Date.parse(raw || "");
+    return Number.isFinite(n) ? n >= cutoff : true;
+  });
+  const removed = rows.length - kept.length;
+  if (removed > 0) writeFileSync(path, JSON.stringify(kept, null, 2), "utf8");
+  return { kept: kept.length, removed };
+}
+
+export function sweepFileAges(dir, { maxAgeMs = 1000 * 60 * 60 * 24 * 30 } = {}) {
+  const root = resolve(dir);
+  if (!existsSync(root)) return { removed: 0 };
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+  for (const name of readdirSync(root)) {
+    const full = join(root, name);
+    const st = statSync(full);
+    if (st.isDirectory()) continue;
+    if (st.mtimeMs < cutoff) {
+      rmSync(full, { force: true });
+      removed += 1;
+    }
+  }
+  return { removed };
+}
+
+export function runRetentionSweep({ root = ".fastscript" } = {}) {
+  const resolved = resolve(root);
+  const cacheResult = sweepFileAges(join(resolved, "cache"), {
+    maxAgeMs: Number(process.env.RETENTION_CACHE_MS || 1000 * 60 * 60 * 24 * 14),
+  });
+  const jobsResult = applyJsonArrayRetention(join(resolved, "jobs-dead-letter.json"), {
+    timestampField: "failedAt",
+    maxAgeMs: Number(process.env.RETENTION_DEAD_LETTER_MS || 1000 * 60 * 60 * 24 * 30),
+  });
+  return {
+    cache: cacheResult,
+    deadLetter: jobsResult,
+  };
+}

package/node_modules/@fastscript/core-private/src/routes.mjs

@@ -0,0 +1,178 @@
+import { dirname, extname, relative } from "node:path";
+
+function cleanSegments(file, pagesDir) {
+  const rel = relative(pagesDir, file).replace(/\\/g, "/").replace(extname(file), "");
+  return rel.split("/").filter(Boolean);
+}
+
+function isGroupSegment(segment) {
+  return segment.startsWith("(") && segment.endsWith(")");
+}
+
+function isParallelSegment(segment) {
+  return segment.startsWith("@");
+}
+
+function normalizeParamType(type) {
+  const raw = String(type || "string").toLowerCase();
+  if (raw === "int" || raw === "float" || raw === "number") return "number";
+  if (raw === "bool" || raw === "boolean") return "boolean";
+  if (raw === "str" || raw === "string") return "string";
+  return "string";
+}
+
+function segmentPriority(segment) {
+  if (!segment) return 0;
+  const token = /^:([A-Za-z_$][\w$]*)(\*)?(\?)?$/.exec(segment);
+  if (!token) return 40;
+  const catchAll = Boolean(token[2]);
+  const optional = Boolean(token[3]);
+  if (catchAll && optional) return 5;
+  if (catchAll) return 10;
+  if (optional) return 20;
+  return 30;
+}
+
+function routePriority(pathname) {
+  const parts = String(pathname || "/").split("/").filter(Boolean);
+  if (!parts.length) return 1000;
+  return parts.reduce((sum, part) => sum + segmentPriority(part), 0) + parts.length;
+}
+
+function routeSegmentValue(segment) {
+  if (!segment) return null;
+  if (isGroupSegment(segment)) return null;
+  if (isParallelSegment(segment)) return null;
+  if (segment === "index") return null;
+  const optionalCatchAll = /^\[\[\.\.\.([A-Za-z_$][\w$]*)\]\]$/.exec(segment);
+  if (optionalCatchAll) {
+    return {
+      value: `:${optionalCatchAll[1]}*?`,
+      param: { name: optionalCatchAll[1], type: "string[] | undefined", optional: true, catchAll: true },
+    };
+  }
+  const requiredCatchAll = /^\[\.\.\.([A-Za-z_$][\w$]*)\]$/.exec(segment);
+  if (requiredCatchAll) {
+    return {
+      value: `:${requiredCatchAll[1]}*`,
+      param: { name: requiredCatchAll[1], type: "string[]", optional: false, catchAll: true },
+    };
+  }
+  const optionalTyped = /^\[\[([A-Za-z_$][\w$]*)(?::([A-Za-z]+))?\]\]$/.exec(segment);
+  if (optionalTyped) {
+    const type = normalizeParamType(optionalTyped[2]);
+    return {
+      value: `:${optionalTyped[1]}?`,
+      param: { name: optionalTyped[1], type: `${type} | undefined`, optional: true, catchAll: false },
+    };
+  }
+  const simpleTyped = /^\[([A-Za-z_$][\w$]*)(?::([A-Za-z]+))?\]$/.exec(segment);
+  if (simpleTyped) {
+    const type = normalizeParamType(simpleTyped[2]);
+    return {
+      value: `:${simpleTyped[1]}`,
+      param: { name: simpleTyped[1], type, optional: false, catchAll: false },
+    };
+  }
+  return { value: segment, param: null };
+}
+
+export function inferRouteMeta(file, pagesDir) {
+  const parts = cleanSegments(file, pagesDir);
+  const pageFile = parts[parts.length - 1] || "index";
+  const parallel = parts.find((segment) => isParallelSegment(segment));
+  const slot = parallel ? parallel.slice(1) : null;
+  const routeParts = [];
+  const params = [];
+  const paramTypes = {};
+
+  for (const part of parts) {
+    const mapped = routeSegmentValue(part);
+    if (!mapped?.value) continue;
+    routeParts.push(mapped.value);
+    if (mapped.param) {
+      params.push(mapped.param.name);
+      paramTypes[mapped.param.name] = mapped.param.type;
+    }
+  }
+
+  const routePath = routeParts.length ? `/${routeParts.join("/")}` : "/";
+  const normalizedParts = parts.filter((segment) => !isGroupSegment(segment) && !isParallelSegment(segment));
+
+  return {
+    file,
+    pageFile,
+    routePath,
+    params,
+    paramTypes,
+    slot,
+    segments: normalizedParts,
+    directory: dirname(relative(pagesDir, file).replace(/\\/g, "/")),
+  };
+}
+
+export function inferRouteParamTypes(routePath, paramTypes = null) {
+  if (paramTypes && typeof paramTypes === "object" && Object.keys(paramTypes).length) {
+    return { ...paramTypes };
+  }
+  const params = {};
+  for (const segment of String(routePath || "").split("/")) {
+    const token = /^:([A-Za-z_$][\w$]*)(\*)?(\?)?$/.exec(segment);
+    if (!token) continue;
+    const name = token[1];
+    const catchAll = Boolean(token[2]);
+    const optional = Boolean(token[3]);
+    if (catchAll && optional) params[name] = "string[] | undefined";
+    else if (catchAll) params[name] = "string[]";
+    else if (optional) params[name] = "string | undefined";
+    else params[name] = "string";
+  }
+  return params;
+}
+
+export function inferRouteLayouts(file, pagesDir, layoutFiles = new Set()) {
+  const relDir = dirname(relative(pagesDir, file).replace(/\\/g, "/"));
+  const chain = [];
+  const dirs = relDir === "." ? [] : relDir.split("/").filter(Boolean);
+  const probes = [""];
+  for (const dir of dirs) {
+    probes.push(probes[probes.length - 1] ? `${probes[probes.length - 1]}/${dir}` : dir);
+  }
+
+  for (const probe of probes) {
+    const fsLayout = probe ? `${probe}/_layout.fs` : "_layout.fs";
+    const jsLayout = probe ? `${probe}/_layout.js` : "_layout.js";
+    if (layoutFiles.has(fsLayout)) chain.push(fsLayout);
+    else if (layoutFiles.has(jsLayout)) chain.push(jsLayout);
+  }
+  return chain;
+}
+
+export function compareRoutePriority(a, b) {
+  const scoreA = routePriority(a?.path || a?.routePath || "/");
+  const scoreB = routePriority(b?.path || b?.routePath || "/");
+  if (scoreA !== scoreB) return scoreB - scoreA;
+
+  const lenA = String(a?.path || a?.routePath || "/").split("/").filter(Boolean).length;
+  const lenB = String(b?.path || b?.routePath || "/").split("/").filter(Boolean).length;
+  if (lenA !== lenB) return lenB - lenA;
+
+  const slotA = String(a?.slot || "default");
+  const slotB = String(b?.slot || "default");
+  if (slotA !== slotB) return slotA.localeCompare(slotB);
+  return String(a?.path || a?.routePath || "/").localeCompare(String(b?.path || b?.routePath || "/"));
+}
+
+export function sortRoutesByPriority(routes = []) {
+  return [...routes].sort(compareRoutePriority);
+}
+
+export function isLayoutFile(file, pagesDir) {
+  const rel = relative(pagesDir, file).replace(/\\/g, "/");
+  return rel.endsWith("/_layout.fs") || rel.endsWith("/_layout.js") || rel === "_layout.fs" || rel === "_layout.js";
+}
+
+export function isNotFoundFile(file, pagesDir) {
+  const rel = relative(pagesDir, file).replace(/\\/g, "/");
+  return rel.endsWith("/404.fs") || rel.endsWith("/404.js") || rel === "404.fs" || rel === "404.js";
+}

package/node_modules/@fastscript/core-private/src/scheduler.mjs

@@ -0,0 +1,104 @@
+function parseField(field, min, max) {
+  const out = new Set();
+  const raw = String(field || "*").trim();
+  if (raw === "*") {
+    for (let i = min; i <= max; i += 1) out.add(i);
+    return out;
+  }
+  for (const part of raw.split(",")) {
+    const item = part.trim();
+    if (!item) continue;
+    const stepSplit = item.split("/");
+    const base = stepSplit[0];
+    const step = Number(stepSplit[1] || 1);
+    const [startRaw, endRaw] = base === "*" ? [String(min), String(max)] : base.split("-");
+    const start = Number(startRaw);
+    const end = Number(endRaw || startRaw);
+    for (let n = start; n <= end; n += step) {
+      if (n >= min && n <= max) out.add(n);
+    }
+  }
+  return out;
+}
+
+function datePartsInTimezone(date, timezone) {
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+    weekday: "short",
+  });
+  const parts = Object.fromEntries(fmt.formatToParts(date).map((p) => [p.type, p.value]));
+  const weekdayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  return {
+    minute: Number(parts.minute),
+    hour: Number(parts.hour),
+    day: Number(parts.day),
+    month: Number(parts.month),
+    weekday: weekdayMap[parts.weekday],
+  };
+}
+
+export function parseCronExpression(expr) {
+  const [minuteRaw, hourRaw, dayRaw, monthRaw, weekdayRaw] = String(expr || "").trim().split(/\s+/);
+  if (!weekdayRaw) {
+    const error = new Error(`Invalid cron expression: ${expr}`);
+    error.status = 400;
+    throw error;
+  }
+  return {
+    minute: parseField(minuteRaw, 0, 59),
+    hour: parseField(hourRaw, 0, 23),
+    day: parseField(dayRaw, 1, 31),
+    month: parseField(monthRaw, 1, 12),
+    weekday: parseField(weekdayRaw, 0, 6),
+  };
+}
+
+export function nextCronRun(expr, { from = new Date(), timezone = "UTC", horizonMinutes = 60 * 24 * 30 } = {}) {
+  const parsed = parseCronExpression(expr);
+  const cursor = new Date(from.getTime());
+  cursor.setSeconds(0, 0);
+  cursor.setMinutes(cursor.getMinutes() + 1);
+  for (let i = 0; i < horizonMinutes; i += 1) {
+    const parts = datePartsInTimezone(cursor, timezone);
+    if (
+      parsed.minute.has(parts.minute) &&
+      parsed.hour.has(parts.hour) &&
+      parsed.day.has(parts.day) &&
+      parsed.month.has(parts.month) &&
+      parsed.weekday.has(parts.weekday)
+    ) {
+      return new Date(cursor.getTime());
+    }
+    cursor.setMinutes(cursor.getMinutes() + 1);
+  }
+  return null;
+}
+
+export function normalizeScheduleEntry(entry = {}) {
+  if (!entry || typeof entry !== "object") return null;
+  if (entry.cron) {
+    const timezone = entry.timezone || "UTC";
+    const next = nextCronRun(entry.cron, { timezone });
+    if (!next) return null;
+    return {
+      ...entry,
+      timezone,
+      nextRunAt: next.getTime(),
+      everyMs: null,
+      dedupeKey: entry.dedupeKey || `cron:${entry.name || "job"}:${timezone}:${entry.cron}`,
+    };
+  }
+  return {
+    ...entry,
+    timezone: entry.timezone || "UTC",
+    everyMs: entry.everyMs ?? 1000,
+    nextRunAt: Date.now() + (entry.everyMs ?? 1000),
+    dedupeKey: entry.dedupeKey || `interval:${entry.name || "job"}`,
+  };
+}