@cronvello/sdk 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to `@cronvello/sdk` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/) (pre-1.0: minor-feature additions ship as patch releases).
 
+## 0.2.0
+
+**The SDK now runs locally with no account.** Until now `@cronvello/sdk` was cloud-coupled: jobs
+only ran once `sync()` had registered them and Cronvello called your app back. This release adds a
+real **local execution engine** and a small **local dashboard**, so the SDK is useful on its own —
+`npx cronvello dev` starts a scheduler loop on your machine and actually fires your handlers when
+they're due, and `--dashboard` opens a live web UI for them. No account, no network. Everything here
+is additive; the cloud `sync()` / dispatch paths are unchanged.
+
+### Added
+
+- **Local engine** — a from-scratch, zero-dependency scheduler. For each job it computes the next
+  fire time from its cron expression (5- or 6-field, `@macros`, ranges/lists/steps/names) and runs
+  the handler when due, enforcing **timezone/DST**, **overlap protection** (`allowConcurrentRuns`),
+  **per-run timeout** (from `callbackTimeoutMs`), and **retry with exponential backoff**
+  (`maxRetries`) — locally. Keeps an in-memory run-history ring buffer and shuts down cleanly.
+- **`cronvello dev [entry]`** — start the local engine from your config module, with a live job
+  table and run feed. `--dry-run [--window <dur>]` prints what would fire in the next window
+  without executing anything.
+- **`cronvello preview "<cron>" [--tz <IANA>] [-n 5]`** — print the next N fire times of any cron
+  expression in a timezone. Also available programmatically as `previewSchedule(expr, opts)`.
+- **`app.dev(options?)`** on the object returned by `defineCronvello` — starts the local engine and
+  returns its handle (`runs()`, `snapshot()`, `stop()`).
+- **`@cronvello/sdk/dev` subpath export** — the engine primitives (`createLocalEngine`,
+  `nextOccurrence`, `previewSchedule`, `upcomingFires`, `startDashboard`, types). `nextOccurrence`
+  and `previewSchedule` are re-exported from the main entry too.
+- **`ctx.signal` on local runs** — the engine aborts it when a run exceeds its timeout, so
+  cooperative handlers can cancel their work.
+- **Local dashboard** — `cronvello dev --dashboard [--port N]` (or `app.dev({ dashboard: true })`)
+  serves a small, zero-dependency web UI over the running engine on `127.0.0.1`: a job table with a
+  live next-fire countdown, a Server-Sent-Events run feed (fire/success/error/timeout/retry/skip), a
+  per-job drawer with recent runs and upcoming fire times, and a **Run now** button. Read-only JSON
+  API plus `GET /api/runs.ndjson` to export the run history. Light + dark, no framework, no network,
+  MIT. Mutating requests are same-origin-guarded. The dashboard code is loaded lazily, so it never
+  weighs down the main bundle.
+- **`engine.subscribe(listener)`**, **`engine.onStop(hook)`**, **`engine.trigger(key)`**, and
+  **`engine.toNdjson()`** on `LocalEngine` — the multi-subscriber, manual-run, and export primitives
+  the dashboard is built on (`engine.stop()` also tears the dashboard down).
+
+### Changed
+
+- **`cronvello dev <jobKey>` (single-shot) is now `cronvello trigger <jobKey>`** (pre-1.0 rename).
+  `cronvello dev` now starts the local engine instead of running one job once. `app.trigger()` is
+  unchanged.
+
 ## 0.1.4
 
 - **Fix the `cronvello` CLI when launched via the `bin` symlink.** The entry-point check compared

package/README.md

@@ -8,6 +8,8 @@ required**. Your jobs always follow your code.
 npm i @cronvello/sdk
 ```
 
+- ✅ **Runs locally with no account** — `npx cronvello dev` starts a real scheduler loop on your
+  machine (timezone/DST, overlap protection, timeouts, retry/backoff). No cloud, no network.
 - ✅ **Zero runtime dependencies** (Node 20+ `fetch` + WebCrypto).
 - ✅ **Dual ESM + CJS**, full TypeScript types.
 - ✅ **Base URL baked in** (`https://api.cronvello.com`) — override only for self-hosting.
@@ -17,7 +19,7 @@ npm i @cronvello/sdk
   raw cron — with **typo-proof validation** at define time.
 - ✅ **Test jobs locally** with `cronvello.trigger("job")` — no deploy, no HTTP.
 - ✅ **Lifecycle hooks** for logging / metrics / error reporting.
-- ✅ **A real CLI** — `npx cronvello whoami | list | runs | status | sync | dev`.
+- ✅ **A real CLI** — `npx cronvello dev | preview | whoami | list | runs | status | sync`.
 
 ---
 
@@ -207,6 +209,134 @@ it("sends digests", async () => {
 
 ---
 
+## Local development (no account) — `cronvello dev`
+
+You don't need a Cronvello account, an API key, or a deploy to run your jobs. **The SDK ships a real
+local engine.** Point the CLI at the module that exports your app and it starts a scheduler loop on
+your machine that actually fires the handlers when they're due — computing each next fire time from
+its cron expression (timezone- and DST-aware) and enforcing the same production policies the cloud
+does: **overlap protection, per-run timeout, and retry with backoff**. No cloud, no network.
+
+```ts
+// cronvello.config.ts
+import { defineCronvello, every, daily } from "@cronvello/sdk";
+
+export const cronvello = defineCronvello({
+  appName: "my-app",
+  appUrl: "https://my-app.example.com",
+  apiKey: "crn_local_dev",            // any non-empty value — the local engine never calls the API
+  dispatchSecret: "local-dev-secret-0123456789abcdef",
+  timeZone: "Europe/Berlin",
+  jobs: {
+    heartbeat:      { schedule: every("10s"), handler: async () => { console.log("beat"); } },
+    "daily-digest": { schedule: daily("08:00"), handler: async () => sendDigests() },
+  },
+});
+```
+
+```bash
+npx cronvello dev                    # auto-detects cronvello.config.{ts,js,mjs} (or pass a path)
+```
+
+```
+◷ Cronvello dev · local engine · no account, no cloud
+
+JOB           SCHEDULE       TZ             NEXT RUN             WHEN
+heartbeat     */10 * * * * *  Europe/Berlin  2026-06-28 18:03:10  in 8s
+daily-digest  0 8 * * *      Europe/Berlin  2026-06-29 08:00:00  in 14h
+
+watching 2 job(s) — press Ctrl-C to stop
+
+18:03:10 → heartbeat fired
+18:03:10 ✔ heartbeat 3ms
+18:03:20 → heartbeat fired
+18:03:20 ✔ heartbeat 2ms
+```
+
+Every fire is logged with its result, duration, retries, and any timeouts; the engine keeps an
+in-memory history of recent runs and shuts down cleanly on `Ctrl-C`. Running a **TypeScript** config
+directly? Launch the CLI under a TS loader:
+
+```bash
+node --import tsx node_modules/@cronvello/sdk/dist/cli.js dev ./cronvello.config.ts
+```
+
+**See what would fire without running anything:**
+
+```bash
+npx cronvello dev --dry-run --window 1h     # lists the fires due in the next hour
+```
+
+**Preview any cron expression** — the next N fire times, in a timezone:
+
+```bash
+npx cronvello preview "0 8 * * 1-5" --tz Europe/Berlin -n 5
+npx cronvello preview "@daily" -n 3
+```
+
+**Run a single job once** (handy in a script or while iterating on one handler):
+
+```bash
+npx cronvello trigger daily-digest
+```
+
+### Local dashboard
+
+Prefer to *see* your schedule? Add `--dashboard` and `cronvello dev` also serves a small local web UI
+on top of the same engine — no account, no cloud, no external network.
+
+```bash
+npx cronvello dev --dashboard            # → http://127.0.0.1:4747  (override with --port)
+```
+
+Open the printed URL and you get, live:
+
+- every **job** with its cron expression, timezone, and a **countdown to the next fire**,
+- a **run feed** that streams each fire, success, error, timeout, retry, and skip as it happens,
+- a **job drawer** with recent runs and the next fire times, plus a **Run now** button that triggers
+  the handler through the engine and shows the result instantly,
+- light + dark, and an honest **disconnected** state if the engine stops.
+
+It binds to `127.0.0.1` by default (it's a dev tool, not a public server) and exposes a tiny
+read-only JSON API plus an SSE stream — including `GET /api/runs.ndjson` to pipe the run history out
+as NDJSON. You can also start it programmatically:
+
+```ts
+const engine = cronvello.dev({ dashboard: true });   // or { dashboard: { port: 5000 } }
+// … engine.stop() closes the dashboard too.
+```
+
+![Cronvello local dashboard](https://unpkg.com/@cronvello/sdk/docs/dashboard.png)
+
+### Embedding the engine
+
+`cronvello dev` is a thin wrapper over `app.dev()`, which you can call yourself — it returns the
+engine handle (run history, snapshot, clean `stop()`):
+
+```ts
+const engine = cronvello.dev();          // starts the local scheduler
+// … later …
+console.log(engine.runs());              // recent run records, newest first
+await engine.stop();                     // drains in-flight runs, clears timers
+```
+
+The lower-level primitives live under the **`@cronvello/sdk/dev`** subpath — including
+`nextOccurrence`, `previewSchedule`, and `createLocalEngine` — so you can build the schedule math
+into your own tooling:
+
+```ts
+import { nextOccurrence, previewSchedule } from "@cronvello/sdk/dev";
+
+nextOccurrence("0 8 * * *", { timeZone: "Europe/Berlin" });  // → next 08:00 in Berlin
+previewSchedule("*/15 * * * *", { count: 4 });               // → the next four fire times
+```
+
+> The local engine is fully MIT and **never makes a network call**. When your jobs are ready for
+> production, `sync()` registers the exact same definitions with Cronvello Cloud — same code, now
+> hosted, with reliability, alerts, and run history. Local is the on-ramp; the cloud is the upsell.
+
+---
+
 ## Lifecycle hooks & logging
 
 Observe every run — for structured logs, metrics, or error reporting (Sentry, etc.). Hooks never
@@ -346,7 +476,10 @@ $ cronvello whoami
 ```bash
 npx cronvello sync ./cronvello.config.js          # reconcile to Cronvello
 npx cronvello sync ./cronvello.config.js --dry     # preview the diff
-npx cronvello dev  ./cronvello.config.js my-job    # run a job's handler locally
+npx cronvello dev  ./cronvello.config.js           # run the jobs locally (the local engine)
+npx cronvello dev  ./cronvello.config.js --dry-run # …or just show what would fire
+npx cronvello preview "0 8 * * 1-5" --tz Europe/Berlin -n 5   # next fire times of an expression
+npx cronvello trigger ./cronvello.config.js my-job # run one job's handler once, locally
 ```
 
 > Running a **TypeScript** config? Launch the CLI under a TS loader: