@cronvello/sdk 0.1.3 → 0.2.0

package/dist/cli.cjs

@@ -1,12 +1,887 @@
 #!/usr/bin/env node
 'use strict';
 
+var http = require('http');
 var module$1 = require('module');
 var url = require('url');
 var path = require('path');
 var fs = require('fs');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var http__default = /*#__PURE__*/_interopDefault(http);
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/internal/cron-schedule.ts
+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(field) {
+  const f = field.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 = resolveValue(base.slice(0, dash), spec);
+        hi = resolveValue(base.slice(dash + 1), spec);
+      } else {
+        lo = resolveValue(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 resolveValue(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;
+}
+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();
+}
+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 out2 = [];
+  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;
+    out2.push(next);
+    from = next.getTime();
+  }
+  return out2;
+}
+function upcomingFires(jobs, opts = {}) {
+  const from = opts.from === void 0 ? Date.now() : typeof opts.from === "number" ? opts.from : opts.from.getTime();
+  const withinMs = opts.withinMs ?? 60 * 60 * 1e3;
+  const maxPerJob = Math.max(1, opts.maxPerJob ?? 50);
+  const horizon = from + withinMs;
+  const fires = [];
+  for (const job of jobs) {
+    let parsed;
+    try {
+      parsed = parseCron(job.schedule);
+    } catch {
+      continue;
+    }
+    if (parsed.reboot) continue;
+    let cursor = from;
+    for (let i = 0; i < maxPerJob; i++) {
+      const next = nextOccurrence(parsed, { from: cursor, timeZone: job.timeZone });
+      if (!next || next.getTime() > horizon) break;
+      fires.push({ key: job.key, time: next, schedule: job.schedule, timeZone: job.timeZone });
+      cursor = next.getTime();
+    }
+  }
+  fires.sort((a, b) => a.time.getTime() - b.time.getTime());
+  return fires;
+}
+function localTimeZone() {
+  try {
+    return new Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+var MACRO_EXPANSIONS, MONTH_NAMES, DOW_NAMES, SECOND_SPEC, MINUTE_SPEC, HOUR_SPEC, DOM_SPEC, MONTH_SPEC, DOW_SPEC, SEARCH_HORIZON_YEARS, FORMATTER_CACHE;
+var init_cron_schedule = __esm({
+  "src/internal/cron-schedule.ts"() {
+    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 * * * *"
+    };
+    MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+    DOW_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+    SECOND_SPEC = { min: 0, max: 59, nameOffset: 0, label: "second" };
+    MINUTE_SPEC = { min: 0, max: 59, nameOffset: 0, label: "minute" };
+    HOUR_SPEC = { min: 0, max: 23, nameOffset: 0, label: "hour" };
+    DOM_SPEC = { min: 1, max: 31, nameOffset: 0, label: "day-of-month" };
+    MONTH_SPEC = { min: 1, max: 12, names: MONTH_NAMES, nameOffset: 1, label: "month" };
+    DOW_SPEC = { min: 0, max: 7, names: DOW_NAMES, nameOffset: 0, fold: (v) => v % 7, label: "day-of-week" };
+    SEARCH_HORIZON_YEARS = 5;
+    FORMATTER_CACHE = /* @__PURE__ */ new Map();
+  }
+});
+
+// src/dev/dashboard-assets.ts
+var DASHBOARD_HTML;
+var init_dashboard_assets = __esm({
+  "src/dev/dashboard-assets.ts"() {
+    DASHBOARD_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>Cronvello \u2014 local dashboard</title>
+<style>
+  :root {
+    --indigo: #4F46E5;
+    --indigo-soft: #6366F1;
+    --teal: #14B8A6;
+    --green: #10B981;
+    --amber: #F59E0B;
+    --red: #EF4444;
+    --bg: #f8fafc;
+    --panel: #ffffff;
+    --panel-2: #f1f5f9;
+    --border: #e2e8f0;
+    --text: #0f172a;
+    --muted: #64748b;
+    --shadow: 0 1px 3px rgba(15, 23, 42, 0.08), 0 1px 2px rgba(15, 23, 42, 0.04);
+  }
+  [data-theme="dark"] {
+    --bg: #0b1120;
+    --panel: #111827;
+    --panel-2: #0f172a;
+    --border: #1f2937;
+    --text: #e5e7eb;
+    --muted: #94a3b8;
+    --shadow: 0 1px 3px rgba(0, 0, 0, 0.5), 0 1px 2px rgba(0, 0, 0, 0.4);
+  }
+  /* Dark-mode-first: follow the OS preference unless the user has explicitly chosen light. */
+  @media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+      --bg: #0b1120;
+      --panel: #111827;
+      --panel-2: #0f172a;
+      --border: #1f2937;
+      --text: #e5e7eb;
+      --muted: #94a3b8;
+      --shadow: 0 1px 3px rgba(0, 0, 0, 0.5), 0 1px 2px rgba(0, 0, 0, 0.4);
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Inter, Roboto, sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+  }
+  code, .mono { font-family: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace; }
+  header {
+    display: flex; align-items: center; gap: 12px;
+    padding: 14px 20px;
+    border-bottom: 1px solid var(--border);
+    background: var(--panel);
+    position: sticky; top: 0; z-index: 10;
+  }
+  .logo {
+    width: 28px; height: 28px; border-radius: 8px;
+    display: grid; place-items: center;
+    background: linear-gradient(135deg, var(--indigo), var(--teal));
+    color: #fff; font-size: 17px; font-weight: 700;
+  }
+  .brand { font-weight: 700; letter-spacing: -0.01em; }
+  .brand small { color: var(--muted); font-weight: 500; margin-left: 6px; }
+  .spacer { flex: 1; }
+  .pill {
+    display: inline-flex; align-items: center; gap: 6px;
+    padding: 4px 10px; border-radius: 999px;
+    font-size: 12px; font-weight: 600;
+    border: 1px solid var(--border); background: var(--panel-2); color: var(--muted);
+  }
+  .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--muted); }
+  .pill.live .dot { background: var(--green); box-shadow: 0 0 0 0 rgba(16,185,129,0.5); animation: pulse 1.8s infinite; }
+  .pill.down .dot { background: var(--red); }
+  @keyframes pulse { 0% { box-shadow: 0 0 0 0 rgba(16,185,129,0.5); } 70% { box-shadow: 0 0 0 6px rgba(16,185,129,0); } 100% { box-shadow: 0 0 0 0 rgba(16,185,129,0); } }
+  button {
+    font: inherit; cursor: pointer; color: var(--text);
+    background: var(--panel-2); border: 1px solid var(--border);
+    border-radius: 8px; padding: 6px 12px;
+  }
+  button:hover { border-color: var(--indigo-soft); }
+  button.primary { background: var(--indigo); color: #fff; border-color: var(--indigo); }
+  button.primary:hover { background: var(--indigo-soft); }
+  .layout { display: grid; grid-template-columns: 1.4fr 1fr; gap: 16px; padding: 16px 20px; align-items: start; }
+  @media (max-width: 860px) { .layout { grid-template-columns: 1fr; } }
+  .card { background: var(--panel); border: 1px solid var(--border); border-radius: 12px; box-shadow: var(--shadow); overflow: hidden; }
+  .card > h2 { margin: 0; padding: 12px 16px; font-size: 13px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); border-bottom: 1px solid var(--border); }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 10px 16px; border-bottom: 1px solid var(--border); vertical-align: middle; }
+  th { font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); font-weight: 600; }
+  tr:last-child td { border-bottom: none; }
+  tbody tr { cursor: pointer; }
+  tbody tr:hover { background: var(--panel-2); }
+  .jobkey { font-weight: 600; }
+  .jobdesc { color: var(--muted); font-size: 12px; }
+  .count { font-variant-numeric: tabular-nums; }
+  .badge { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 11px; font-weight: 700; }
+  .badge.success { background: rgba(16,185,129,0.15); color: var(--green); }
+  .badge.error, .badge.timed_out { background: rgba(239,68,68,0.15); color: var(--red); }
+  .badge.skipped { background: rgba(100,116,139,0.18); color: var(--muted); }
+  .badge.running { background: rgba(79,70,229,0.15); color: var(--indigo-soft); }
+  .badge.none { background: var(--panel-2); color: var(--muted); }
+  .feed { max-height: 70vh; overflow-y: auto; }
+  .ev { display: flex; gap: 10px; padding: 8px 16px; border-bottom: 1px solid var(--border); font-size: 13px; }
+  .ev .glyph { width: 16px; text-align: center; flex: none; }
+  .ev .body { flex: 1; min-width: 0; }
+  .ev .when { color: var(--muted); font-size: 11px; font-variant-numeric: tabular-nums; }
+  .ev.success .glyph { color: var(--green); }
+  .ev.error .glyph, .ev.timeout .glyph { color: var(--red); }
+  .ev.retry .glyph { color: var(--amber); }
+  .ev.fire .glyph { color: var(--indigo-soft); }
+  .ev.skipped .glyph, .ev.scheduled .glyph, .ev.engine .glyph { color: var(--muted); }
+  .empty { padding: 24px 16px; color: var(--muted); text-align: center; }
+  footer { padding: 12px 20px 28px; color: var(--muted); font-size: 12px; }
+  .overlay { position: fixed; inset: 0; background: rgba(15,23,42,0.45); display: none; align-items: stretch; justify-content: flex-end; z-index: 30; }
+  .overlay.open { display: flex; }
+  .drawer { width: min(520px, 92vw); background: var(--panel); border-left: 1px solid var(--border); height: 100%; overflow-y: auto; box-shadow: var(--shadow); }
+  .drawer header { background: var(--panel); }
+  .drawer .pad { padding: 16px; }
+  .kv { display: flex; gap: 8px; margin: 4px 0; }
+  .kv span:first-child { color: var(--muted); min-width: 90px; }
+  .section-title { font-size: 11px; text-transform: uppercase; letter-spacing: 0.04em; color: var(--muted); margin: 18px 0 8px; }
+  ul.plain { list-style: none; margin: 0; padding: 0; }
+  ul.plain li { padding: 6px 0; border-bottom: 1px solid var(--border); display: flex; justify-content: space-between; gap: 8px; }
+</style>
+</head>
+<body>
+<header>
+  <div class="logo">&#8635;</div>
+  <div class="brand">Cronvello <small>local dashboard</small></div>
+  <div class="spacer"></div>
+  <span id="conn" class="pill"><span class="dot"></span><span id="conn-text">connecting&hellip;</span></span>
+  <button id="theme-btn" title="Toggle theme">&#9788;</button>
+</header>
+
+<div class="layout">
+  <section class="card">
+    <h2>Jobs &mdash; next fire &amp; last status</h2>
+    <table>
+      <thead><tr><th>Job</th><th>Schedule</th><th>Timezone</th><th>Next fire</th><th>Last</th></tr></thead>
+      <tbody id="jobs"><tr><td colspan="5" class="empty">Loading jobs&hellip;</td></tr></tbody>
+    </table>
+  </section>
+
+  <section class="card">
+    <h2>Live run feed</h2>
+    <div id="feed" class="feed"><div class="empty">Waiting for runs&hellip;</div></div>
+  </section>
+</div>
+
+<footer>Local &middot; no account &middot; no cloud &middot; no external network. The engine on this machine is the only source of truth.</footer>
+
+<div id="overlay" class="overlay">
+  <div class="drawer">
+    <header>
+      <div class="brand" id="drawer-title">Job</div>
+      <div class="spacer"></div>
+      <button id="drawer-close">Close</button>
+    </header>
+    <div class="pad" id="drawer-body"></div>
+  </div>
+</div>
+
+<script>
+(function () {
+  "use strict";
+  var MAX_FEED = 200;
+  var jobsByKey = {};
+
+  function el(id) { return document.getElementById(id); }
+  function esc(s) {
+    return String(s == null ? "" : s).replace(/[&<>"']/g, function (c) {
+      return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c];
+    });
+  }
+  function pad(n) { return n < 10 ? "0" + n : "" + n; }
+  function clockTime(ms) {
+    var d = new Date(ms);
+    return pad(d.getHours()) + ":" + pad(d.getMinutes()) + ":" + pad(d.getSeconds());
+  }
+  function fmtDuration(ms) {
+    if (ms == null) return "";
+    if (ms < 1000) return ms + "ms";
+    return (ms / 1000).toFixed(ms < 10000 ? 2 : 1) + "s";
+  }
+  function countdown(iso) {
+    if (!iso) return "&mdash;";
+    var diff = new Date(iso).getTime() - Date.now();
+    if (diff <= 0) return "due now";
+    var s = Math.floor(diff / 1000);
+    var d = Math.floor(s / 86400); s -= d * 86400;
+    var h = Math.floor(s / 3600); s -= h * 3600;
+    var m = Math.floor(s / 60); s -= m * 60;
+    var out = "in ";
+    if (d) out += d + "d ";
+    if (d || h) out += h + "h ";
+    if (d || h || m) out += m + "m ";
+    out += s + "s";
+    return out;
+  }
+
+  // \u2500\u2500 Theme \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  function applyTheme(t) {
+    if (t === "dark" || t === "light") document.documentElement.setAttribute("data-theme", t);
+    else document.documentElement.removeAttribute("data-theme");
+  }
+  function resolvedTheme() {
+    var t = document.documentElement.getAttribute("data-theme");
+    if (t) return t;
+    return window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  try { applyTheme(localStorage.getItem("cronvello-theme")); } catch (e) {}
+  el("theme-btn").addEventListener("click", function () {
+    var next = resolvedTheme() === "dark" ? "light" : "dark";
+    applyTheme(next);
+    try { localStorage.setItem("cronvello-theme", next); } catch (e) {}
+  });
+
+  // \u2500\u2500 Jobs table \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  function statusBadge(s) {
+    if (!s) return '<span class="badge none">&mdash;</span>';
+    return '<span class="badge ' + esc(s) + '">' + esc(s) + "</span>";
+  }
+  function renderJobs(jobs) {
+    jobsByKey = {};
+    if (!jobs.length) { el("jobs").innerHTML = '<tr><td colspan="5" class="empty">No jobs registered.</td></tr>'; return; }
+    var rows = "";
+    for (var i = 0; i < jobs.length; i++) {
+      var j = jobs[i];
+      jobsByKey[j.key] = j;
+      var last = j.running ? "running" : (j.lastStatus || "");
+      rows +=
+        '<tr data-key="' + esc(j.key) + '">' +
+        "<td><div class=\\"jobkey\\">" + esc(j.key) + "</div>" + (j.description ? '<div class="jobdesc">' + esc(j.description) + "</div>" : "") + "</td>" +
+        '<td><code>' + esc(j.schedule) + "</code></td>" +
+        "<td>" + esc(j.timeZone) + "</td>" +
+        '<td class="count" data-next="' + esc(j.nextFire || "") + '">' + countdown(j.nextFire) + "</td>" +
+        "<td>" + (j.running ? '<span class="badge running">running</span>' : statusBadge(j.lastStatus)) + "</td>" +
+        "</tr>";
+    }
+    el("jobs").innerHTML = rows;
+    var trs = el("jobs").querySelectorAll("tr[data-key]");
+    for (var k = 0; k < trs.length; k++) {
+      trs[k].addEventListener("click", function () { openDrawer(this.getAttribute("data-key")); });
+    }
+  }
+  function tickCountdowns() {
+    var cells = el("jobs").querySelectorAll("td[data-next]");
+    for (var i = 0; i < cells.length; i++) {
+      var iso = cells[i].getAttribute("data-next");
+      cells[i].innerHTML = iso ? countdown(iso) : "&mdash;";
+    }
+  }
+
+  function loadJobs() {
+    return fetch("/api/jobs").then(function (r) { return r.json(); }).then(function (jobs) {
+      // Fold in each job's last run so the table can show a status without a per-row fetch.
+      return fetch("/api/runs").then(function (r) { return r.json(); }).then(function (runs) {
+        var lastByKey = {};
+        for (var i = 0; i < runs.length; i++) { if (!lastByKey[runs[i].key]) lastByKey[runs[i].key] = runs[i]; }
+        for (var j = 0; j < jobs.length; j++) {
+          var lr = lastByKey[jobs[j].key];
+          jobs[j].lastStatus = lr ? lr.status : "";
+        }
+        renderJobs(jobs);
+      });
+    }).catch(function () {});
+  }
+
+  // \u2500\u2500 Live feed \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  var glyphs = { fire: "&#9655;", success: "&#10003;", error: "&#10007;", timeout: "&#9203;", retry: "&#8635;", skipped: "&#8866;", scheduled: "&#128337;", "engine-start": "&#9889;", "engine-stop": "&#9632;" };
+  function describe(ev) {
+    switch (ev.type) {
+      case "fire": return "<strong>" + esc(ev.key) + "</strong> fired" + (ev.attempt > 1 ? " (attempt " + ev.attempt + ")" : "");
+      case "success": return "<strong>" + esc(ev.key) + "</strong> succeeded in " + fmtDuration(ev.durationMs) + (ev.attempts > 1 ? " after " + ev.attempts + " attempts" : "");
+      case "error": return "<strong>" + esc(ev.key) + "</strong> errored: " + esc(ev.error) + (ev.willRetry ? " \u2014 will retry" : "");
+      case "timeout": return "<strong>" + esc(ev.key) + "</strong> timed out after " + fmtDuration(ev.durationMs) + (ev.willRetry ? " \u2014 will retry" : "");
+      case "retry": return "<strong>" + esc(ev.key) + "</strong> retrying (attempt " + ev.attempt + ") in " + fmtDuration(ev.delayMs);
+      case "skipped": return "<strong>" + esc(ev.key) + "</strong> skipped (overlap)";
+      case "scheduled": return "<strong>" + esc(ev.key) + "</strong> scheduled";
+      case "engine-start": return "Engine started \u2014 " + ev.jobs + " job(s)";
+      case "engine-stop": return "Engine stopped";
+      default: return esc(ev.type);
+    }
+  }
+  function feedClass(type) {
+    if (type === "engine-start" || type === "engine-stop" || type === "scheduled") return "engine";
+    return type;
+  }
+  function pushEvent(ev) {
+    var feed = el("feed");
+    if (feed.firstChild && feed.firstChild.className === "empty") feed.innerHTML = "";
+    var div = document.createElement("div");
+    div.className = "ev " + feedClass(ev.type);
+    div.innerHTML =
+      '<div class="glyph">' + (glyphs[ev.type] || "&#8226;") + "</div>" +
+      '<div class="body">' + describe(ev) + "</div>" +
+      '<div class="when">' + clockTime(ev.at || Date.now()) + "</div>";
+    feed.insertBefore(div, feed.firstChild);
+    while (feed.childNodes.length > MAX_FEED) feed.removeChild(feed.lastChild);
+
+    // A terminal event changes a job's last status / running flag \u2014 refresh the table.
+    if (ev.type === "success" || ev.type === "error" || ev.type === "timeout" || ev.type === "skipped" || ev.type === "scheduled") {
+      loadJobs();
+    }
+  }
+
+  function setConn(state) {
+    var pill = el("conn"), text = el("conn-text");
+    pill.className = "pill " + state;
+    text.textContent = state === "live" ? "live" : (state === "down" ? "disconnected" : "connecting\u2026");
+  }
+
+  function connect() {
+    setConn("connecting");
+    var src = new EventSource("/api/events");
+    src.onopen = function () { setConn("live"); };
+    src.onmessage = function (m) {
+      try { pushEvent(JSON.parse(m.data)); } catch (e) {}
+    };
+    src.onerror = function () { setConn("down"); };
+  }
+
+  // \u2500\u2500 Job drawer \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  function openDrawer(key) {
+    var job = jobsByKey[key];
+    if (!job) return;
+    el("drawer-title").textContent = key;
+    el("drawer-body").innerHTML = '<div class="empty">Loading&hellip;</div>';
+    el("overlay").classList.add("open");
+
+    Promise.all([
+      fetch("/api/preview/" + encodeURIComponent(key) + "?n=5").then(function (r) { return r.json(); }).catch(function () { return []; }),
+      fetch("/api/runs/" + encodeURIComponent(key)).then(function (r) { return r.json(); }).catch(function () { return []; })
+    ]).then(function (res) {
+      var fires = res[0] || [], runs = res[1] || [];
+      var html =
+        '<div class="kv"><span>Schedule</span><code>' + esc(job.schedule) + "</code></div>" +
+        '<div class="kv"><span>Timezone</span><span>' + esc(job.timeZone) + "</span></div>" +
+        (job.description ? '<div class="kv"><span>Description</span><span>' + esc(job.description) + "</span></div>" : "") +
+        '<div style="margin-top:14px"><button class="primary" id="run-now">Run now</button></div>' +
+        '<div class="section-title">Next fire times</div>';
+      if (fires.length) {
+        html += '<ul class="plain">';
+        for (var i = 0; i < fires.length; i++) html += "<li><span>" + esc(new Date(fires[i]).toLocaleString()) + "</span><span class=\\"count\\">" + countdown(fires[i]) + "</span></li>";
+        html += "</ul>";
+      } else { html += '<div class="empty">No upcoming fires.</div>'; }
+
+      html += '<div class="section-title">Recent runs</div>';
+      if (runs.length) {
+        html += '<ul class="plain">';
+        for (var j = 0; j < runs.length && j < 20; j++) {
+          var run = runs[j];
+          html += "<li><span>" + statusBadge(run.status) + " <span class=\\"when\\">" + esc(new Date(run.startedAt).toLocaleString()) + "</span></span><span>" + fmtDuration(run.durationMs) + "</span></li>";
+        }
+        html += "</ul>";
+      } else { html += '<div class="empty">No runs yet.</div>'; }
+
+      el("drawer-body").innerHTML = html;
+      el("run-now").addEventListener("click", function () { runNow(key, this); });
+    });
+  }
+  function closeDrawer() { el("overlay").classList.remove("open"); }
+  el("drawer-close").addEventListener("click", closeDrawer);
+  el("overlay").addEventListener("click", function (e) { if (e.target === el("overlay")) closeDrawer(); });
+
+  function runNow(key, btn) {
+    btn.disabled = true; btn.textContent = "Running\u2026";
+    fetch("/api/trigger/" + encodeURIComponent(key), { method: "POST", headers: { "content-type": "application/json" } })
+      .then(function (r) { return r.json(); })
+      .then(function () { btn.textContent = "Ran \u2713"; setTimeout(function () { openDrawer(key); }, 600); loadJobs(); })
+      .catch(function () { btn.disabled = false; btn.textContent = "Run now"; });
+  }
+
+  // \u2500\u2500 Boot \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  loadJobs();
+  connect();
+  setInterval(tickCountdowns, 1000);
+  setInterval(loadJobs, 15000);
+})();
+</script>
+</body>
+</html>`;
+  }
+});
+
+// src/dev/dashboard.ts
+var dashboard_exports = {};
+__export(dashboard_exports, {
+  startDashboard: () => startDashboard
+});
+function startDashboard(engine, options = {}) {
+  const host = options.host ?? DEFAULT_HOST;
+  const port = options.port ?? DEFAULT_PORT;
+  const sseClients = /* @__PURE__ */ new Set();
+  const server = http__default.default.createServer((req, res) => handleRequest(engine, sseClients, req, res));
+  return new Promise((resolve2, reject) => {
+    const onError = (err) => {
+      server.removeListener("error", onError);
+      if (err.code === "EADDRINUSE") {
+        reject(new Error(`Cronvello dashboard: port ${port} on ${host} is already in use \u2014 pass a different --port.`));
+      } else {
+        reject(err);
+      }
+    };
+    server.once("error", onError);
+    server.listen(port, host, () => {
+      server.removeListener("error", onError);
+      const actualPort = server.address().port;
+      const shown = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+      const url = `http://${shown}:${actualPort}`;
+      let closed = false;
+      const close = () => {
+        if (closed) return Promise.resolve();
+        closed = true;
+        for (const client of sseClients) client.end();
+        sseClients.clear();
+        return new Promise((res2) => {
+          server.closeAllConnections?.();
+          server.close(() => res2());
+        });
+      };
+      resolve2({ url, port: actualPort, close });
+    });
+  });
+}
+function handleRequest(engine, sseClients, req, res) {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const path = url.pathname;
+  const method = req.method ?? "GET";
+  if (method === "GET" && path === "/") {
+    return sendHtml(res, DASHBOARD_HTML);
+  }
+  if (method === "GET" && path === "/api/events") {
+    return openEventStream(engine, sseClients, req, res);
+  }
+  if (method === "GET" && path === "/api/health") {
+    return sendJson(res, 200, { ok: true, jobs: engine.jobs().length, activeRuns: engine.activeRuns });
+  }
+  if (method === "GET" && path === "/api/runs.ndjson") {
+    res.writeHead(200, { "content-type": "application/x-ndjson; charset=utf-8", "cache-control": "no-store" });
+    const body = engine.toNdjson();
+    return void res.end(body.length ? body + "\n" : "");
+  }
+  if (method === "GET" && path === "/api/runs") {
+    const key = url.searchParams.get("key");
+    return sendJson(res, 200, key ? engine.runsFor(key) : engine.runs());
+  }
+  if (method === "GET" && path.startsWith("/api/runs/")) {
+    return sendJson(res, 200, engine.runsFor(decodeKey(path, "/api/runs/")));
+  }
+  if (method === "GET" && path.startsWith("/api/preview/")) {
+    const key = decodeKey(path, "/api/preview/");
+    const job = engine.snapshot().find((j) => j.key === key);
+    if (!job) return sendJson(res, 404, { error: `unknown job '${key}'` });
+    const n = clampCount(url.searchParams.get("n"));
+    try {
+      const fires = previewSchedule(job.schedule, { timeZone: job.timeZone, count: n });
+      return sendJson(res, 200, fires.map((d) => d.toISOString()));
+    } catch {
+      return sendJson(res, 200, []);
+    }
+  }
+  if (method === "GET" && path === "/api/jobs") {
+    const jobs = engine.snapshot().map((j) => ({
+      key: j.key,
+      schedule: j.schedule,
+      timeZone: j.timeZone,
+      description: j.description,
+      nextFire: j.nextFire ? j.nextFire.toISOString() : null,
+      running: j.running
+    }));
+    return sendJson(res, 200, jobs);
+  }
+  if (method === "POST" && path.startsWith("/api/trigger/")) {
+    if (!isSameOrigin(req)) return sendJson(res, 403, { error: "cross-origin request rejected" });
+    const key = decodeKey(path, "/api/trigger/");
+    return void engine.trigger(key).then((record) => sendJson(res, 200, record)).catch((err) => {
+      const status = /unknown job/.test(err.message) ? 404 : 400;
+      sendJson(res, status, { error: err.message });
+    });
+  }
+  sendJson(res, 404, { error: "not found" });
+}
+function openEventStream(engine, sseClients, req, res) {
+  res.writeHead(200, {
+    "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-store",
+    connection: "keep-alive",
+    "x-accel-buffering": "no"
+  });
+  res.write(": connected\n\n");
+  sseClients.add(res);
+  const unsubscribe = engine.subscribe((event) => {
+    res.write(`data: ${JSON.stringify(event)}
+
+`);
+  });
+  const heartbeat = setInterval(() => res.write(": ping\n\n"), HEARTBEAT_MS);
+  if (typeof heartbeat.unref === "function") heartbeat.unref();
+  const cleanup = () => {
+    clearInterval(heartbeat);
+    unsubscribe();
+    sseClients.delete(res);
+  };
+  res.on("close", cleanup);
+  req.on("close", cleanup);
+}
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+  res.end(payload);
+}
+function sendHtml(res, html) {
+  res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+  res.end(html);
+}
+function decodeKey(path, prefix) {
+  return decodeURIComponent(path.slice(prefix.length));
+}
+function clampCount(raw) {
+  const n = raw ? Number.parseInt(raw, 10) : 5;
+  if (!Number.isFinite(n) || n < 1) return 5;
+  return Math.min(n, MAX_PREVIEW);
+}
+function isSameOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  try {
+    return new URL(origin).host === req.headers.host;
+  } catch {
+    return false;
+  }
+}
+var DEFAULT_PORT, DEFAULT_HOST, HEARTBEAT_MS, MAX_PREVIEW;
+var init_dashboard = __esm({
+  "src/dev/dashboard.ts"() {
+    init_cron_schedule();
+    init_dashboard_assets();
+    DEFAULT_PORT = 4747;
+    DEFAULT_HOST = "127.0.0.1";
+    HEARTBEAT_MS = 15e3;
+    MAX_PREVIEW = 50;
+  }
+});
+
 // src/internal/errors.ts
 var CronvelloError = class extends Error {
   constructor(message) {
@@ -406,8 +1281,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 c2 of sorted) {
+  const sorted2 = [...result.changes].sort((a, b) => order.indexOf(a.action) - order.indexOf(b.action));
+  for (const c2 of sorted2) {
     const g = GLYPH[c2.action];
     const detail = c2.changedFields && c2.changedFields.length ? paint(` (${c2.changedFields.join(", ")})`, "gray") : c2.reason ? paint(` (${c2.reason})`, "gray") : "";
     lines.push(`  ${paint(g.sign, g.color)} ${paint(c2.action.padEnd(9), g.color)} ${c2.key}${detail}`);
@@ -432,6 +1307,9 @@ function generateDispatchSecret(bytes = 32) {
   return Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/cli/index.ts
+init_cron_schedule();
+
 // src/cli/ui.ts
 var E = String.fromCharCode(27);
 var ENV = typeof process !== "undefined" && process.env ? process.env : {};
@@ -516,6 +1394,8 @@ var VERSION = (() => {
     return "0.0.0";
   }
 })();
+var VALUE_FLAGS = ["limit", "status", "job", "type", "runType", "tz", "window", "count", "n", "port", "host"];
+var SHORT_VALUE_FLAGS = ["n", "c"];
 function parseArgs(argv) {
   const positionals = [];
   const flags = {};
@@ -524,14 +1404,21 @@ function parseArgs(argv) {
     if (a.startsWith("--")) {
       const key = a.slice(2);
       const next = argv[i + 1];
-      if (next !== void 0 && !next.startsWith("-") && ["limit", "status", "job", "type", "runType"].includes(key)) {
+      if (next !== void 0 && !next.startsWith("-") && VALUE_FLAGS.includes(key)) {
         flags[key] = next;
         i++;
       } else {
         flags[key] = true;
       }
     } else if (a.startsWith("-") && a.length > 1) {
-      flags[a.slice(1)] = true;
+      const key = a.slice(1);
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("-") && SHORT_VALUE_FLAGS.includes(key)) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
     } else {
       positionals.push(a);
     }
@@ -708,10 +1595,81 @@ async function cmdSync(positionals, flags, useJson) {
   if (useJson) return json(result);
   out(formatSyncResult(result, { color: true, dryRun }));
 }
-async function cmdDev(positionals, useJson) {
+async function cmdDevEngine(positionals, flags, useJson) {
+  const app = await loadApp(positionals[0]);
+  const dryRun = !!flags["dry-run"] || !!flags["dry"];
+  if (dryRun) {
+    const engine2 = app.dev({ autoStart: false, installSignalHandlers: false });
+    const windowMs = parseDurationFlag(flags["window"], 60 * 60 * 1e3);
+    const maxPerJob = 50;
+    const fires = upcomingFires(
+      engine2.jobs().map((j) => ({ key: j.key, schedule: j.schedule, timeZone: j.timeZone })),
+      { withinMs: windowMs, maxPerJob }
+    );
+    const cappedJobs = [...new Set(fires.map((f) => f.key))].filter(
+      (key) => fires.filter((f) => f.key === key).length >= maxPerJob
+    );
+    if (useJson) {
+      return json({
+        window: { ms: windowMs },
+        capped: cappedJobs,
+        fires: fires.map((f) => ({ key: f.key, time: f.time.toISOString(), schedule: f.schedule, timeZone: f.timeZone }))
+      });
+    }
+    header(`dev \xB7 dry-run \xB7 next ${formatDuration(windowMs)}`);
+    out(renderUpcoming(fires));
+    out();
+    out(c.gray(fires.length ? `${fires.length} fire(s) would run \u2014 no handlers were executed` : "nothing scheduled in this window"));
+    if (cappedJobs.length) {
+      out(c.yellow(`\u25B2 output capped at ${maxPerJob} per job (${cappedJobs.join(", ")}) \u2014 high-frequency schedule, not the full window`));
+    }
+    return;
+  }
+  const engine = app.dev({ autoStart: false, installSignalHandlers: false, onEvent: (e) => renderEvent(e, useJson) });
+  engine.start();
+  let dashboardUrl;
+  if (flags["dashboard"]) {
+    const { startDashboard: startDashboard2 } = await Promise.resolve().then(() => (init_dashboard(), dashboard_exports));
+    const port = typeof flags["port"] === "string" ? Number.parseInt(flags["port"], 10) : void 0;
+    const host = typeof flags["host"] === "string" ? flags["host"] : void 0;
+    try {
+      const dash = await startDashboard2(engine, { port, host });
+      dashboardUrl = dash.url;
+      engine.onStop(() => dash.close());
+    } catch (err) {
+      await engine.stop();
+      throw err;
+    }
+  }
+  if (!useJson) {
+    header(`dev \xB7 local engine ${c.gray("\xB7 no account, no cloud")}`);
+    out(renderSchedule(engine.snapshot()));
+    out();
+    if (dashboardUrl) out(`${sym.ok} dashboard \u2192 ${c.cyan(dashboardUrl)}`);
+    out(c.gray(`watching ${engine.jobs().length} job(s) \u2014 press Ctrl-C to stop`));
+    out();
+  }
+  await new Promise((resolve2) => {
+    const onSignal = () => {
+      process.removeListener("SIGINT", onSignal);
+      process.removeListener("SIGTERM", onSignal);
+      void engine.stop().then(resolve2);
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+  });
+  if (!useJson) {
+    out();
+    const runs = engine.runs();
+    const ok = runs.filter((r) => r.status === "success").length;
+    const bad = runs.filter((r) => r.status === "error" || r.status === "timed_out").length;
+    out(c.gray(`stopped \u2014 ${runs.length} run(s) this session (${ok} ok${bad ? `, ${c.red(`${bad} failed`)}` : ""})`));
+  }
+}
+async function cmdTrigger(positionals, useJson) {
   const jobKey = positionals[positionals.length - 1];
   const configPath = positionals.length >= 2 ? positionals[0] : void 0;
-  if (!jobKey) throw new CronvelloConfigError("Usage: cronvello dev [configPath] <jobKey>");
+  if (!jobKey) throw new CronvelloConfigError("Usage: cronvello trigger [configPath] <jobKey>");
   const app = await loadApp(configPath);
   if (!app.keys().includes(jobKey)) {
     throw new CronvelloConfigError(`Unknown job "${jobKey}". Known: ${app.keys().join(", ") || "(none)"}`);
@@ -726,6 +1684,123 @@ async function cmdDev(positionals, useJson) {
     out(JSON.stringify(result, null, 2).split("\n").map((l) => "  " + l).join("\n"));
   }
 }
+function cmdPreview(positionals, flags, useJson) {
+  const expr = positionals[0];
+  if (!expr) throw new CronvelloConfigError('Usage: cronvello preview "<cron>" [--tz <IANA>] [-n 5]');
+  const tz = typeof flags["tz"] === "string" ? flags["tz"] : localTimeZone();
+  const count = clampLimit(flags["n"] ?? flags["count"] ?? flags["limit"]);
+  let times;
+  try {
+    times = previewSchedule(expr, { timeZone: tz, count });
+  } catch (err) {
+    throw new CronvelloConfigError(err instanceof Error ? err.message : String(err));
+  }
+  if (useJson) return json({ schedule: expr, timeZone: tz, next: times.map((t) => t.toISOString()) });
+  header(`preview ${c.cyan(expr)} ${c.gray(`\xB7 ${tz}`)}`);
+  if (!times.length) {
+    out(c.gray("no upcoming fire times (does this expression ever match?)"));
+    return;
+  }
+  const now = Date.now();
+  out(
+    table(
+      [{ header: "#", align: "right" }, { header: "LOCAL TIME" }, { header: "WHEN" }, { header: "UTC" }],
+      times.map((t, i) => [
+        c.gray(String(i + 1)),
+        c.bold(formatInZone(t, tz)),
+        relativeTime(t.toISOString(), now),
+        c.gray(t.toISOString())
+      ])
+    )
+  );
+}
+function renderSchedule(snapshot) {
+  const now = Date.now();
+  return table(
+    [{ header: "JOB" }, { header: "SCHEDULE" }, { header: "TZ" }, { header: "NEXT RUN" }, { header: "WHEN" }],
+    snapshot.map((s) => [
+      c.bold(s.key),
+      c.cyan(s.schedule),
+      c.gray(s.timeZone),
+      s.nextFire ? formatInZone(s.nextFire, s.timeZone) : c.gray("\u2014"),
+      s.nextFire ? relativeTime(s.nextFire.toISOString(), now) : c.gray("\u2014")
+    ])
+  );
+}
+function renderUpcoming(fires) {
+  const now = Date.now();
+  return table(
+    [{ header: "WHEN" }, { header: "LOCAL TIME" }, { header: "JOB" }, { header: "SCHEDULE" }],
+    fires.map((f) => [
+      relativeTime(f.time.toISOString(), now),
+      c.bold(formatInZone(f.time, f.timeZone)),
+      c.cyan(f.key),
+      c.gray(f.schedule)
+    ])
+  );
+}
+function renderEvent(event, useJson) {
+  if (useJson) return out(JSON.stringify(event));
+  const ts = c.gray(clockStamp(Date.now()));
+  switch (event.type) {
+    case "fire":
+      out(`${ts} ${sym.arrow} ${c.bold(event.key)} ${c.gray(event.attempt > 1 ? `(attempt ${event.attempt})` : "fired")}`);
+      break;
+    case "success":
+      out(`${ts} ${sym.ok} ${c.bold(event.key)} ${c.gray(`${event.durationMs}ms${event.attempts > 1 ? ` \xB7 ${event.attempts} attempts` : ""}`)}`);
+      break;
+    case "error":
+      out(`${ts} ${sym.fail} ${c.bold(event.key)} ${c.red(event.error)} ${c.gray(event.willRetry ? "\xB7 will retry" : "\xB7 gave up")}`);
+      break;
+    case "timeout":
+      out(`${ts} ${sym.fail} ${c.bold(event.key)} ${c.red("timed out")} ${c.gray(`after ${event.durationMs}ms${event.willRetry ? " \xB7 will retry" : " \xB7 gave up"}`)}`);
+      break;
+    case "retry":
+      out(`${ts} ${sym.warn} ${c.bold(event.key)} ${c.gray(`retrying in ${event.delayMs}ms (attempt ${event.attempt})`)}`);
+      break;
+    case "skipped":
+      out(`${ts} ${sym.warn} ${c.bold(event.key)} ${c.gray("skipped \u2014 previous run still in flight")}`);
+      break;
+  }
+}
+function formatInZone(date, timeZone) {
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false
+    }).formatToParts(date);
+    const m = {};
+    for (const p of parts) if (p.type !== "literal") m[p.type] = p.value;
+    const hour = m["hour"] === "24" ? "00" : m["hour"];
+    return `${m["year"]}-${m["month"]}-${m["day"]} ${hour}:${m["minute"]}:${m["second"]}`;
+  } catch {
+    return date.toISOString();
+  }
+}
+function clockStamp(nowMs) {
+  return formatInZone(new Date(nowMs), localTimeZone()).slice(11);
+}
+function parseDurationFlag(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  const m = /^(\d+)\s*(s|m|h|d)?$/i.exec(value.trim());
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  const unit = (m[2] ?? "m").toLowerCase();
+  const mult = unit === "s" ? 1e3 : unit === "h" ? 36e5 : unit === "d" ? 864e5 : 6e4;
+  return n * mult;
+}
+function formatDuration(ms) {
+  if (ms % 864e5 === 0) return `${ms / 864e5}d`;
+  if (ms % 36e5 === 0) return `${ms / 36e5}h`;
+  if (ms % 6e4 === 0) return `${ms / 6e4}m`;
+  return `${Math.round(ms / 1e3)}s`;
+}
 function cmdSecret(useJson) {
   const secret = generateDispatchSecret();
   if (useJson) return json({ dispatchSecret: secret });
@@ -787,7 +1862,10 @@ function printHelp() {
     ["run <taskId>", "trigger a task now (or: run <jobName> <taskName>)"],
     ["status", "health overview + recent failures"],
     ["sync [path] [--dry]", "reconcile a code registry (loads your module)"],
-    ["dev [path] <jobKey>", "run a job handler locally, no deploy"],
+    ["dev [path] [--dry-run]", "start the local engine \u2014 run jobs locally, no account"],
+    ["dev --dashboard [--port n]", "\u2026plus a local web dashboard (127.0.0.1, live runs + run-now)"],
+    ['preview "<cron>" [-n 5]', "print the next N fire times (--tz <IANA>)"],
+    ["trigger [path] <jobKey>", "run a single job handler once, locally"],
     ["secret", "generate a strong dispatch secret"]
   ];
   for (const [name, desc] of cmds) out(`  ${c.cyan(name.padEnd(30))} ${c.gray(desc)}`);
@@ -844,7 +1922,13 @@ async function run(argv) {
         await cmdSync(args.positionals, args.flags, useJson);
         break;
       case "dev":
-        await cmdDev(args.positionals, useJson);
+        await cmdDevEngine(args.positionals, args.flags, useJson);
+        break;
+      case "preview":
+        cmdPreview(args.positionals, args.flags, useJson);
+        break;
+      case "trigger":
+        await cmdTrigger(args.positionals, useJson);
         break;
       case "secret":
         cmdSecret(useJson);
@@ -865,8 +1949,20 @@ async function run(argv) {
     return 1;
   }
 }
-var invokedDirectly = typeof process !== "undefined" && Array.isArray(process.argv) && /[\\/]cli\.(c?js|ts)$/.test(process.argv[1] ?? "");
-if (invokedDirectly) {
+function isMainModule() {
+  try {
+    const argv1 = process.argv?.[1];
+    if (!argv1) return false;
+    return fs.realpathSync(argv1) === fs.realpathSync(url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href))));
+  } catch {
+    return false;
+  }
+}
+if (isMainModule()) {
+  process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE") process.exit(0);
+    throw err;
+  });
   run(process.argv.slice(2)).then((code) => {
     process.exitCode = code;
   });