@cronvello/sdk 0.1.4 → 0.2.0

package/dist/index.cjs

@@ -528,7 +528,7 @@ function createDispatcher(state) {
       throw error;
     }
   }
-  function buildContext(key, job, req, body, isAsync, source) {
+  function buildContext(key, job, req, body, isAsync, source, signal) {
     return {
       key,
       schedule: typeof body["schedule"] === "string" ? body["schedule"] : job.config.schedule ?? "",
@@ -538,7 +538,7 @@ function createDispatcher(state) {
       isAsync,
       source,
       logger: log,
-      signal: req?.signal
+      signal: req?.signal ?? signal
     };
   }
   async function handle(req) {
@@ -588,11 +588,11 @@ function createDispatcher(state) {
       return resp(500, { ok: false, job: key, error: err instanceof Error ? err.message : String(err) });
     }
   }
-  async function runLocal(key, payload) {
+  async function runLocal(key, payload, opts) {
     const job = state.jobs.get(key);
     if (!job) throw new Error(`Unknown job '${key}'. Known: ${[...state.jobs.keys()].join(", ") || "(none)"}`);
     const body = { job: key, schedule: job.config.schedule, ...payload ?? {} };
-    const ctx = buildContext(key, job, null, body, false, "local");
+    const ctx = buildContext(key, job, null, body, false, "local", opts?.signal);
     const { result } = await invokeHandler(job, ctx);
     return result;
   }
@@ -879,6 +879,610 @@ function nextHandler(app) {
   };
 }
 
+// src/internal/cron-schedule.ts
+var MACRO_EXPANSIONS = {
+  "@yearly": "0 0 1 1 *",
+  "@annually": "0 0 1 1 *",
+  "@monthly": "0 0 1 * *",
+  "@weekly": "0 0 * * 0",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@hourly": "0 * * * *"
+};
+var MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+var DOW_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+var SECOND_SPEC = { min: 0, max: 59, nameOffset: 0, label: "second" };
+var MINUTE_SPEC = { min: 0, max: 59, nameOffset: 0, label: "minute" };
+var HOUR_SPEC = { min: 0, max: 23, nameOffset: 0, label: "hour" };
+var DOM_SPEC = { min: 1, max: 31, nameOffset: 0, label: "day-of-month" };
+var MONTH_SPEC = { min: 1, max: 12, names: MONTH_NAMES, nameOffset: 1, label: "month" };
+var DOW_SPEC = { min: 0, max: 7, names: DOW_NAMES, nameOffset: 0, fold: (v) => v % 7, label: "day-of-week" };
+function parseCron(expr) {
+  if (typeof expr !== "string" || !expr.trim()) throw new Error("cron expression is empty");
+  let trimmed = expr.trim();
+  if (trimmed.startsWith("@")) {
+    const macro = trimmed.toLowerCase();
+    if (macro === "@reboot") {
+      return {
+        seconds: /* @__PURE__ */ new Set([0]),
+        minutes: /* @__PURE__ */ new Set(),
+        hours: /* @__PURE__ */ new Set(),
+        daysOfMonth: /* @__PURE__ */ new Set(),
+        months: /* @__PURE__ */ new Set(),
+        daysOfWeek: /* @__PURE__ */ new Set(),
+        domRestricted: false,
+        dowRestricted: false,
+        reboot: true
+      };
+    }
+    const expanded = MACRO_EXPANSIONS[macro];
+    if (!expanded) throw new Error(`unknown cron macro "${trimmed}" (try @daily, @hourly, \u2026)`);
+    trimmed = expanded;
+  }
+  const parts = trimmed.split(/\s+/);
+  if (parts.length !== 5 && parts.length !== 6) {
+    throw new Error(`expected 5 fields (min hour dom month dow) or 6 with seconds, got ${parts.length}: "${trimmed}"`);
+  }
+  const hasSeconds = parts.length === 6;
+  const [secRaw, minRaw, hourRaw, domRaw, monthRaw, dowRaw] = hasSeconds ? parts : ["0", ...parts];
+  return {
+    seconds: expandField(secRaw, SECOND_SPEC),
+    minutes: expandField(minRaw, MINUTE_SPEC),
+    hours: expandField(hourRaw, HOUR_SPEC),
+    daysOfMonth: expandField(domRaw, DOM_SPEC),
+    months: expandField(monthRaw, MONTH_SPEC),
+    daysOfWeek: expandField(dowRaw, DOW_SPEC),
+    domRestricted: isRestricted(domRaw),
+    dowRestricted: isRestricted(dowRaw),
+    reboot: false
+  };
+}
+function isRestricted(field2) {
+  const f = field2.trim();
+  return f !== "*" && f !== "?";
+}
+function expandField(raw, spec) {
+  const set = /* @__PURE__ */ new Set();
+  for (const term of raw.split(",")) {
+    if (term === "") throw new Error(`empty term in ${spec.label} field "${raw}"`);
+    let base = term;
+    let step = 1;
+    const slash = term.indexOf("/");
+    if (slash >= 0) {
+      base = term.slice(0, slash);
+      const stepStr = term.slice(slash + 1);
+      if (!/^\d+$/.test(stepStr) || Number(stepStr) === 0) {
+        throw new Error(`invalid step "${stepStr}" in ${spec.label} field "${raw}"`);
+      }
+      step = Number(stepStr);
+    }
+    let lo;
+    let hi;
+    if (base === "*" || base === "?") {
+      lo = spec.min;
+      hi = spec.max;
+    } else {
+      const dash = base.indexOf("-");
+      if (dash > 0) {
+        lo = resolveValue2(base.slice(0, dash), spec);
+        hi = resolveValue2(base.slice(dash + 1), spec);
+      } else {
+        lo = resolveValue2(base, spec);
+        hi = step > 1 ? spec.max : lo;
+      }
+    }
+    if (lo === null || hi === null) {
+      throw new Error(`value out of range in ${spec.label} field "${raw}" (${spec.min}-${spec.max})`);
+    }
+    if (lo > hi) throw new Error(`range start ${lo} is greater than end ${hi} in ${spec.label} field "${raw}"`);
+    for (let v = lo; v <= hi; v += step) set.add(spec.fold ? spec.fold(v) : v);
+  }
+  return set;
+}
+function resolveValue2(token, spec) {
+  const t = token.trim();
+  if (/^\d+$/.test(t)) {
+    const n = Number(t);
+    return n >= spec.min && n <= spec.max ? n : null;
+  }
+  if (spec.names) {
+    const idx = spec.names.indexOf(t.toLowerCase());
+    if (idx >= 0) return idx + spec.nameOffset;
+  }
+  return null;
+}
+var SEARCH_HORIZON_YEARS = 5;
+function nextOccurrence(expr, opts = {}) {
+  const parsed = typeof expr === "string" ? parseCron(expr) : expr;
+  if (parsed.reboot) throw new Error("@reboot has no scheduled next occurrence (the engine fires it once at start)");
+  const tz = opts.timeZone ?? "UTC";
+  const fromMs = opts.from === void 0 ? Date.now() : typeof opts.from === "number" ? opts.from : opts.from.getTime();
+  const cursor = Math.floor(fromMs / 1e3) * 1e3 + 1e3;
+  const p = getZonedParts(cursor, tz);
+  const startYear = p.y;
+  const hourArr = sorted(parsed.hours);
+  const minuteArr = sorted(parsed.minutes);
+  const secondArr = sorted(parsed.seconds);
+  let guard = 0;
+  while (guard++ < 1e6) {
+    if (p.y > startYear + SEARCH_HORIZON_YEARS) return null;
+    if (!parsed.months.has(p.mo)) {
+      bumpMonth(p);
+      continue;
+    }
+    if (p.d > daysInMonth(p.y, p.mo)) {
+      bumpMonth(p);
+      continue;
+    }
+    if (!dayMatches(parsed, p.y, p.mo, p.d)) {
+      bumpDay(p);
+      continue;
+    }
+    const nh = firstAtLeast(hourArr, p.h);
+    if (nh === null) {
+      bumpDay(p);
+      continue;
+    }
+    if (nh !== p.h) {
+      p.h = nh;
+      p.mi = 0;
+      p.s = 0;
+    }
+    const nmi = firstAtLeast(minuteArr, p.mi);
+    if (nmi === null) {
+      p.h += 1;
+      p.mi = 0;
+      p.s = 0;
+      continue;
+    }
+    if (nmi !== p.mi) {
+      p.mi = nmi;
+      p.s = 0;
+    }
+    const ns = firstAtLeast(secondArr, p.s);
+    if (ns === null) {
+      p.mi += 1;
+      p.s = 0;
+      continue;
+    }
+    p.s = ns;
+    const epoch = zonedWallToEpoch(p, tz);
+    if (epoch <= fromMs) {
+      p.s += 1;
+      continue;
+    }
+    return new Date(epoch);
+  }
+  throw new Error(`nextOccurrence: search exceeded its iteration bound for "${typeof expr === "string" ? expr : "(parsed)"}"`);
+}
+function dayMatches(parsed, y, mo, d) {
+  const domOk = parsed.daysOfMonth.has(d);
+  const dowOk = parsed.daysOfWeek.has(weekdayOf(y, mo, d));
+  if (parsed.domRestricted && parsed.dowRestricted) return domOk || dowOk;
+  if (parsed.domRestricted) return domOk;
+  if (parsed.dowRestricted) return dowOk;
+  return true;
+}
+function bumpMonth(p) {
+  p.mo += 1;
+  if (p.mo > 12) {
+    p.mo = 1;
+    p.y += 1;
+  }
+  p.d = 1;
+  p.h = 0;
+  p.mi = 0;
+  p.s = 0;
+}
+function bumpDay(p) {
+  p.d += 1;
+  p.h = 0;
+  p.mi = 0;
+  p.s = 0;
+}
+function sorted(set) {
+  return [...set].sort((a, b) => a - b);
+}
+function firstAtLeast(arr, v) {
+  for (const x of arr) if (x >= v) return x;
+  return null;
+}
+function daysInMonth(year, month) {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function weekdayOf(year, month, day) {
+  return new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+}
+var FORMATTER_CACHE = /* @__PURE__ */ new Map();
+function formatterFor(timeZone) {
+  let fmt = FORMATTER_CACHE.get(timeZone);
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false
+    });
+    FORMATTER_CACHE.set(timeZone, fmt);
+  }
+  return fmt;
+}
+function getZonedParts(epochMs, timeZone) {
+  const parts = formatterFor(timeZone).formatToParts(new Date(epochMs));
+  const m = {};
+  for (const part of parts) if (part.type !== "literal") m[part.type] = part.value;
+  let h = Number(m["hour"]);
+  if (h === 24) h = 0;
+  return { y: Number(m["year"]), mo: Number(m["month"]), d: Number(m["day"]), h, mi: Number(m["minute"]), s: Number(m["second"]) };
+}
+function offsetAt(epochMs, timeZone) {
+  const p = getZonedParts(epochMs, timeZone);
+  const asNaive = Date.UTC(p.y, p.mo - 1, p.d, p.h, p.mi, p.s);
+  return asNaive - epochMs;
+}
+function zonedWallToEpoch(p, timeZone) {
+  const asUTC = Date.UTC(p.y, p.mo - 1, p.d, p.h, p.mi, p.s);
+  const o1 = offsetAt(asUTC, timeZone);
+  let epoch = asUTC - o1;
+  const o2 = offsetAt(epoch, timeZone);
+  if (o2 !== o1) epoch = asUTC - o2;
+  return epoch;
+}
+function previewSchedule(expr, opts = {}) {
+  const parsed = parseCron(expr);
+  const timeZone = opts.timeZone ?? localTimeZone();
+  const count = Math.min(Math.max(Math.trunc(opts.count ?? 5), 1), 100);
+  const out = [];
+  let from = opts.from === void 0 ? Date.now() : typeof opts.from === "number" ? opts.from : opts.from.getTime();
+  for (let i = 0; i < count; i++) {
+    const next = nextOccurrence(parsed, { from, timeZone });
+    if (!next) break;
+    out.push(next);
+    from = next.getTime();
+  }
+  return out;
+}
+function localTimeZone() {
+  try {
+    return new Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+// src/dev/engine.ts
+var DEFAULT_HISTORY_LIMIT = 100;
+var MAX_TIMER_MS = 2 ** 31 - 1;
+function defaultBackoff(attempt) {
+  return Math.min(3e4, 500 * 2 ** (attempt - 1));
+}
+var realClock = {
+  now: () => Date.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (handle) => clearTimeout(handle)
+};
+var RunTimeoutError = class extends Error {
+  constructor(key, ms) {
+    super(`job '${key}' timed out after ${ms}ms`);
+    this.name = "RunTimeoutError";
+  }
+};
+function createLocalEngine(jobs, runner, options = {}) {
+  return new LocalEngine(jobs, runner, options);
+}
+var LocalEngine = class {
+  clock;
+  /** Every event listener. The constructor's `onEvent` is registered as one of them. */
+  listeners = /* @__PURE__ */ new Set();
+  /** Run after the engine has drained, e.g. to close a dashboard server. */
+  closeHooks = [];
+  historyLimit;
+  backoff;
+  runner;
+  states;
+  history = [];
+  inFlight = /* @__PURE__ */ new Set();
+  started = false;
+  stopped = false;
+  signalCleanup = null;
+  constructor(jobs, runner, options = {}) {
+    this.clock = options.clock ?? realClock;
+    if (options.onEvent) this.listeners.add(options.onEvent);
+    this.historyLimit = Math.max(1, options.historyLimit ?? DEFAULT_HISTORY_LIMIT);
+    this.backoff = options.backoff ?? defaultBackoff;
+    this.runner = runner;
+    this.states = jobs.map((job) => ({
+      job,
+      nextFire: null,
+      timer: null,
+      running: false,
+      isReboot: job.schedule.trim().toLowerCase() === "@reboot"
+    }));
+    if (options.installSignalHandlers) this.installSignalHandlers();
+  }
+  /**
+   * Subscribe to every lifecycle event (in addition to the constructor's `onEvent`). Returns an
+   * unsubscribe function. Used by the local dashboard to fan events out to many SSE clients without
+   * disturbing the scheduler. A listener that throws is isolated — it can't break the loop.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  /**
+   * Register a hook to run once, after {@link stop} has drained in-flight runs — e.g. to close a
+   * dashboard server so `engine.stop()` tears everything down together. Hooks are awaited.
+   */
+  onStop(hook) {
+    this.closeHooks.push(hook);
+    return this;
+  }
+  /** Deliver an event to every listener, isolating each so one bad listener can't stall the loop. */
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  /** Begin scheduling. Idempotent — a second call is a no-op. */
+  start() {
+    if (this.started) return this;
+    this.started = true;
+    this.stopped = false;
+    this.emit({ type: "engine-start", jobs: this.states.length, at: this.clock.now() });
+    for (const state of this.states) {
+      if (state.isReboot) {
+        this.launch(state);
+      } else {
+        this.scheduleNext(state);
+      }
+    }
+    return this;
+  }
+  /**
+   * Stop scheduling and wait for in-flight runs to settle. After this resolves no further handlers
+   * will start. Safe to call from a signal handler.
+   */
+  async stop() {
+    if (this.stopped) {
+      await Promise.allSettled([...this.inFlight]);
+      return;
+    }
+    this.stopped = true;
+    for (const state of this.states) {
+      if (state.timer !== null) {
+        this.clock.clearTimeout(state.timer);
+        state.timer = null;
+      }
+    }
+    this.signalCleanup?.();
+    this.signalCleanup = null;
+    await Promise.allSettled([...this.inFlight]);
+    this.emit({ type: "engine-stop", at: this.clock.now() });
+    for (const hook of this.closeHooks.splice(0)) {
+      try {
+        await hook();
+      } catch {
+      }
+    }
+  }
+  /** The run history, newest first (a copy — safe to keep). */
+  runs() {
+    return [...this.history].reverse();
+  }
+  /** History entries for one job, newest first. */
+  runsFor(key) {
+    return this.runs().filter((r) => r.key === key);
+  }
+  /** Current scheduling state of every job, for the dev table. */
+  snapshot() {
+    return this.states.map((s) => ({
+      key: s.job.key,
+      schedule: s.job.schedule,
+      timeZone: s.job.timeZone,
+      ...s.job.description !== void 0 ? { description: s.job.description } : {},
+      nextFire: s.nextFire !== null ? new Date(s.nextFire) : null,
+      running: s.running
+    }));
+  }
+  /** The jobs this engine manages (read-only view). */
+  jobs() {
+    return this.states.map((s) => s.job);
+  }
+  /** Number of runs currently in flight. */
+  get activeRuns() {
+    return this.inFlight.size;
+  }
+  // ── Scheduling ─────────────────────────────────────────────────────────────
+  scheduleNext(state) {
+    if (this.stopped) return;
+    const now = this.clock.now();
+    let next;
+    try {
+      next = nextOccurrence(state.job.schedule, { from: now, timeZone: state.job.timeZone });
+    } catch {
+      state.nextFire = null;
+      return;
+    }
+    if (!next) {
+      state.nextFire = null;
+      return;
+    }
+    state.nextFire = next.getTime();
+    const delay = Math.max(0, Math.min(state.nextFire - now, MAX_TIMER_MS));
+    state.timer = this.clock.setTimeout(() => this.onDue(state), delay);
+    this.emit({ type: "scheduled", key: state.job.key, at: state.nextFire });
+  }
+  onDue(state) {
+    state.timer = null;
+    if (this.stopped) return;
+    const now = this.clock.now();
+    if (state.nextFire !== null && now < state.nextFire) {
+      const delay = Math.max(0, Math.min(state.nextFire - now, MAX_TIMER_MS));
+      state.timer = this.clock.setTimeout(() => this.onDue(state), delay);
+      return;
+    }
+    if (state.running && !state.job.allowConcurrentRuns) {
+      this.emit({ type: "skipped", key: state.job.key, reason: "overlap", at: now });
+      this.record({
+        key: state.job.key,
+        source: "local",
+        startedAt: now,
+        finishedAt: now,
+        durationMs: 0,
+        status: "skipped",
+        attempts: 0
+      });
+    } else {
+      this.launch(state);
+    }
+    this.scheduleNext(state);
+  }
+  /**
+   * Run a job once, right now, by key — the local equivalent of "run now" in the cloud. Goes through
+   * the exact same execution path as a scheduled fire (overlap protection, timeout, retry/backoff,
+   * history + events), so a manual run shows up in the feed just like any other. Resolves with the
+   * resulting {@link RunRecord}. Throws for an unknown key or after the engine has stopped.
+   */
+  async trigger(key) {
+    if (this.stopped) throw new Error("cannot trigger a job on a stopped engine");
+    const state = this.states.find((s) => s.job.key === key);
+    if (!state) throw new Error(`unknown job '${key}'`);
+    if (state.running && !state.job.allowConcurrentRuns) {
+      const now = this.clock.now();
+      const skipped = { key, source: "local", startedAt: now, finishedAt: now, durationMs: 0, status: "skipped", attempts: 0 };
+      this.emit({ type: "skipped", key, reason: "overlap", at: now });
+      this.record(skipped);
+      return skipped;
+    }
+    return this.launch(state);
+  }
+  /**
+   * The run history as newline-delimited JSON (NDJSON), oldest run first — one record per line, the
+   * natural shape for piping to a file or another tool. No trailing newline.
+   */
+  toNdjson() {
+    return this.history.map((r) => JSON.stringify(r)).join("\n");
+  }
+  /** Start an execution and track it so {@link stop} can await it. Resolves with the run's record. */
+  launch(state) {
+    const promise = this.execute(state);
+    const tracked = promise.finally(() => {
+      this.inFlight.delete(tracked);
+    });
+    this.inFlight.add(tracked);
+    return tracked;
+  }
+  // ── Execution with timeout + retry/backoff ──────────────────────────────────
+  async execute(state) {
+    const job = state.job;
+    state.running = true;
+    const startedAt = this.clock.now();
+    const maxRetries = Math.max(0, job.maxRetries ?? 0);
+    let attempt = 0;
+    let status = "error";
+    let error;
+    let result;
+    while (!this.stopped) {
+      attempt++;
+      this.emit({ type: "fire", key: job.key, attempt, at: this.clock.now() });
+      try {
+        result = await this.runOnce(job);
+        status = "success";
+        this.emit({ type: "success", key: job.key, durationMs: this.clock.now() - startedAt, attempts: attempt, result, at: this.clock.now() });
+        error = void 0;
+        break;
+      } catch (err) {
+        const timedOut = err instanceof RunTimeoutError;
+        status = timedOut ? "timed_out" : "error";
+        error = err instanceof Error ? err.message : String(err);
+        const willRetry = attempt <= maxRetries && !this.stopped;
+        const at = this.clock.now();
+        if (timedOut) {
+          this.emit({ type: "timeout", key: job.key, durationMs: at - startedAt, attempt, willRetry, at });
+        } else {
+          this.emit({ type: "error", key: job.key, durationMs: at - startedAt, attempt, willRetry, error, at });
+        }
+        if (!willRetry) break;
+        const delayMs = this.backoff(attempt);
+        this.emit({ type: "retry", key: job.key, attempt: attempt + 1, delayMs, at });
+        await this.sleep(delayMs);
+      }
+    }
+    const finishedAt = this.clock.now();
+    const record = {
+      key: job.key,
+      source: "local",
+      startedAt,
+      finishedAt,
+      durationMs: finishedAt - startedAt,
+      status,
+      attempts: attempt,
+      ...error !== void 0 ? { error } : {},
+      ...status === "success" ? { result } : {}
+    };
+    this.record(record);
+    state.running = false;
+    return record;
+  }
+  /** A single attempt: run the handler, racing it against the per-job timeout. */
+  runOnce(job) {
+    const controller = new AbortController();
+    const handlerPromise = this.runner(job.key, controller.signal);
+    const timeoutMs = job.timeoutMs;
+    if (!timeoutMs || timeoutMs <= 0) return handlerPromise;
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timer = this.clock.setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        controller.abort();
+        reject(new RunTimeoutError(job.key, timeoutMs));
+      }, timeoutMs);
+      handlerPromise.then(
+        (value) => {
+          if (settled) return;
+          settled = true;
+          this.clock.clearTimeout(timer);
+          resolve(value);
+        },
+        (err) => {
+          if (settled) return;
+          settled = true;
+          this.clock.clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  sleep(ms) {
+    return new Promise((resolve) => this.clock.setTimeout(resolve, ms));
+  }
+  record(record) {
+    this.history.push(record);
+    if (this.history.length > this.historyLimit) this.history.shift();
+  }
+  installSignalHandlers() {
+    const handler = () => {
+      void this.stop().then(() => process.exit(0));
+    };
+    process.once("SIGINT", handler);
+    process.once("SIGTERM", handler);
+    this.signalCleanup = () => {
+      process.removeListener("SIGINT", handler);
+      process.removeListener("SIGTERM", handler);
+    };
+  }
+};
+
 // src/registry/define.ts
 var DEFAULT_DISPATCH_PATH = "/cronvello/dispatch";
 var DEFAULT_TIME_ZONE = "Europe/Berlin";
@@ -972,10 +1576,43 @@ function defineCronvello(config) {
     handle: dispatcher.handle,
     expressHandler: () => expressHandler(app),
     nextHandler: () => nextHandler(app),
+    dev(options) {
+      const { autoStart = true, dashboard, ...engineOptions } = options ?? {};
+      const engineJobs = buildEngineJobs([...jobs.values()], defaultTimeZone);
+      const runner = (key, signal) => dispatcher.runLocal(key, void 0, { signal });
+      const engine = createLocalEngine(engineJobs, runner, engineOptions);
+      if (autoStart) engine.start();
+      if (dashboard) {
+        const dashboardOptions = dashboard === true ? {} : dashboard;
+        const devSubpath = "@cronvello/sdk/dev";
+        void import(devSubpath).then(({ startDashboard }) => startDashboard(engine, dashboardOptions)).then((handle) => {
+          engine.onStop(() => handle.close());
+          console.log(`Cronvello dashboard \u2192 ${handle.url}`);
+        }).catch((err) => console.error(`Cronvello dashboard failed to start: ${err.message}`));
+      }
+      return engine;
+    },
     keys: () => [...jobs.keys()]
   };
   return app;
 }
+function buildEngineJobs(jobs, defaultTimeZone) {
+  const engineJobs = [];
+  for (const { key, config } of jobs) {
+    if (config.enabled === false) continue;
+    const job = {
+      key,
+      schedule: config.schedule,
+      timeZone: config.timeZone ?? defaultTimeZone,
+      allowConcurrentRuns: config.allowConcurrentRuns ?? false,
+      maxRetries: config.maxRetries ?? 0
+    };
+    if (config.callbackTimeoutMs !== void 0) job.timeoutMs = config.callbackTimeoutMs;
+    if (config.description !== void 0) job.description = config.description;
+    engineJobs.push(job);
+  }
+  return engineJobs;
+}
 ((defineCronvello2) => {
   function fromEnv(config, env = typeof process !== "undefined" ? process.env : {}) {
     const apiKey = config.apiKey ?? env["CRONVELLO_API_KEY"];
@@ -1104,8 +1741,8 @@ function formatSyncResult(result, options = {}) {
     `${paint("Cronvello", "cyan")} ${verb} ${paint(`"${result.jobName}"`, "bold")} ${paint(`(${result.jobId})`, "gray")}`
   );
   const order = ["created", "updated", "deleted", "skipped", "unchanged"];
-  const sorted = [...result.changes].sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action));
-  for (const c of sorted) {
+  const sorted2 = [...result.changes].sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action));
+  for (const c of sorted2) {
     const g = GLYPH[c.action];
     const detail = c.changedFields && c.changedFields.length ? paint(` (${c.changedFields.join(", ")})`, "gray") : c.reason ? paint(` (${c.reason})`, "gray") : "";
     lines.push(`  ${paint(g.sign, g.color)} ${paint(c.action.padEnd(9), g.color)} ${c.key}${detail}`);
@@ -1244,6 +1881,8 @@ exports.generateDispatchSecret = generateDispatchSecret;
 exports.hourly = hourly;
 exports.isValidTimeZone = isValidTimeZone;
 exports.monthly = monthly;
+exports.nextOccurrence = nextOccurrence;
+exports.previewSchedule = previewSchedule;
 exports.schedule = schedule;
 exports.validateCron = validateCron;
 exports.weekdays = weekdays;