bullpane 0.5.1

package/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2026 Matheus Morett
+
+Bullpane is open core. Its source is licensed in two parts:
+
+* Every file inside a directory named `ee` (today `apps/server/src/ee/` and
+  `apps/web/src/ee/`) is licensed under the Bullpane Commercial License, in the
+  `LICENSE` file inside that directory. That is the code of the Pro features.
+* Everything else in this repository is licensed under the MIT license below.
+
+Releases up to and including 0.3.0 were published entirely under the MIT
+license, and those copies keep it.
+
+---
+
+MIT License
+
+Copyright (c) 2026 Matheus Morett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE-ee

@@ -0,0 +1,46 @@
+Bullpane Commercial License
+
+Copyright (c) 2026 Matheus Morett
+
+This license covers every file inside a directory named `ee` in the Bullpane
+source code (the "Pro Software"). Everything outside those directories is
+licensed under the MIT license in the root `LICENSE` file.
+
+1. Production use requires a subscription. You may use the Pro Software in
+   production only while you hold a valid Bullpane Pro subscription or license
+   key, and only on the number of installations it covers.
+
+2. What you may do without a subscription. You may read, copy and modify the
+   Pro Software, and run it for development and testing. You may also run it,
+   unmodified, as part of the free edition of Bullpane, where the Pro features
+   stay locked until a valid license key is activated.
+
+3. What you may not do:
+   (a) remove, disable, bypass or alter the license key verification, the
+       edition and feature checks, or any other mechanism that limits the Pro
+       features to licensed installations, or use a build in which any of them
+       was removed, disabled, bypassed or altered;
+   (b) sell, rent, sublicense, or offer as a hosted service the Pro Software or
+       any work derived from it;
+   (c) distribute the Pro Software or any work derived from it, except as part
+       of a copy of the Bullpane source code that keeps every mechanism listed
+       in (a) intact and keeps this file;
+   (d) remove or alter this notice or any copyright notice.
+
+4. Modifications. You may make modifications only for the uses allowed above.
+   The licensor keeps all rights to the Pro Software and to any modifications
+   of it you choose to submit back, which are licensed to the licensor as
+   described in `CONTRIBUTING.md`.
+
+5. Third-party components keep their own licenses.
+
+6. Termination. If you break any of these terms, your rights under this license
+   end immediately.
+
+THE PRO SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE PRO SOFTWARE OR THE USE OR OTHER DEALINGS IN THE PRO
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# Bullpane
+
+**A fast, self-hosted dashboard for [BullMQ](https://bullmq.io) and BullMQ Pro.**
+
+```sh
+npx bullpane --redis redis://localhost:6379
+```
+
+Open <http://localhost:3000>. That is the whole install: no database to set up, no account, no login.
+
+<img src="https://bullpane.com/shots/overview.jpg" alt="Bullpane overview: every queue of a connection with counts, rates and the ones that need attention" width="880">
+
+[bullpane.com](https://bullpane.com) · [Live demo](https://demo.bullpane.com) · [GitHub](https://github.com/madmorett/bullpane) · [Changelog](https://bullpane.com/changelog)
+
+## What you get
+
+- Every queue on a Redis, with counts, success rate and what needs attention.
+- Jobs by state, search inside job data, job detail with data, return value, stack trace and logs.
+- Retry, promote, remove and bulk actions through the official `bullmq` API. Pause, resume, clean, drain.
+- Job schedulers, flows (parent/child trees), stalled jobs, Redis health.
+- BullMQ Pro groups: per-group concurrency, rate limits and paused groups.
+- Safe on a busy production Redis: no `KEYS`, one round trip per read, payloads truncated inside Redis.
+
+Works with BullMQ 4, 5 and 6 on Redis, Redis Cluster and Valkey, and with BullMQ Pro.
+
+**Pro** (USD 39/month, one installation, unlimited users) adds login with roles, SSO, alerts to Slack or webhooks, folders, a flow graph, an audit log and an MCP server for Claude and other AI clients.
+
+## Options
+
+```
+npx bullpane [--redis <url>] [options]
+
+  --redis <url>          Redis your BullMQ workers use, added as a connection
+  --prefix <prefix>      BullMQ prefix of that connection (default: bull)
+  --port <port>          HTTP port (default: 3000)
+  --host <host>          Interface to listen on (default: 127.0.0.1)
+  --data-dir <dir>       Where the SQLite database lives (default: ~/.bullpane)
+  --database-url <url>   mysql://user:pass@host:3306/db to use MySQL instead
+  --read-only            Refuse every write with 423
+```
+
+The free edition has no login, so it listens on `127.0.0.1` by default. Use `--host 0.0.0.0` only on a private network, or unlock Pro for login and roles.
+
+Every environment variable of the Docker image works here too.
+
+## Running it for a team
+
+Use the Docker image, next to your stack:
+
+```sh
+docker run -d -p 3000:3000 -v bullpane-data:/data bullpane/bullpane
+```
+
+## Versus bull-board
+
+bull-board is a middleware you mount in your app: a viewer, with no search inside job data, no roles and no alerts. Bullpane runs on its own, so it never ships with your app and can be put in front of production. A full comparison is at [bullpane.com/vs/bull-board](https://bullpane.com/vs/bull-board).
+
+## License
+
+Open core. The bundle contains the free core (MIT) and the Pro features, which are licensed under the Bullpane Commercial License (`LICENSE-ee`): readable, free for development and testing, a subscription for production. See `LICENSE`.

package/bin/bullpane.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * `npx bullpane` — the dashboard without Docker. Same server as the image,
+ * bundled; SQLite in ~/.bullpane unless DATABASE_URL says otherwise.
+ *
+ * Flags win over environment variables, which win over the defaults below.
+ * Every variable the image honours (docs: apps/server/README.md) works here too.
+ */
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const { version } = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+
+const HELP = `Bullpane ${version} — self-hosted dashboard for BullMQ and BullMQ Pro
+
+Usage
+  npx bullpane [--redis <url>] [options]
+
+Options
+  --redis <url>          Redis your BullMQ workers use, added as a connection
+                         (e.g. redis://localhost:6379). More can be added in the UI.
+  --prefix <prefix>      BullMQ prefix of that connection (default: bull)
+  --port <port>          HTTP port (default: 3000, or $PORT)
+  --host <host>          Interface to listen on (default: 127.0.0.1). The free
+                         edition has no login: only use 0.0.0.0 on a private network.
+  --data-dir <dir>       Where the SQLite database lives (default: ~/.bullpane)
+  --database-url <url>   mysql://user:pass@host:3306/db to use MySQL instead
+  --read-only            Refuse every write (retry, remove, pause...) with 423
+  -v, --version          Print the version
+  -h, --help             Print this help
+
+Docs: https://bullpane.com · Docker: ghcr.io/madmorett/bullpane`;
+
+let args;
+try {
+  args = parseArgs({
+    options: {
+      redis: { type: "string" },
+      prefix: { type: "string" },
+      port: { type: "string" },
+      host: { type: "string" },
+      "data-dir": { type: "string" },
+      "database-url": { type: "string" },
+      "read-only": { type: "boolean" },
+      version: { type: "boolean", short: "v" },
+      help: { type: "boolean", short: "h" },
+    },
+    strict: true,
+  }).values;
+} catch (err) {
+  console.error(`${err.message}\n\n${HELP}`);
+  process.exit(2);
+}
+
+if (args.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+if (args.version) {
+  console.log(version);
+  process.exit(0);
+}
+
+const env = process.env;
+const set = (key, flag, fallback) => {
+  if (flag !== undefined) env[key] = String(flag);
+  else if (env[key] === undefined || env[key] === "") {
+    if (fallback !== undefined) env[key] = String(fallback);
+  }
+};
+
+set("PORT", args.port, 3000);
+set("HOST", args.host, "127.0.0.1");
+set("BULLPANE_DATA_DIR", args["data-dir"], path.join(homedir(), ".bullpane"));
+set("DATABASE_URL", args["database-url"]);
+set("BULLPANE_READ_ONLY", args["read-only"] ? "true" : undefined);
+set("WEB_DIST", undefined, path.join(root, "web"));
+set("PUBLIC_URL", undefined, `http://localhost:${env.PORT}`);
+set("NODE_ENV", undefined, "production");
+
+if (args.redis) {
+  let name = "Redis";
+  try {
+    const u = new URL(args.redis);
+    name = `${u.hostname}${u.port ? `:${u.port}` : ""}`; // never the password
+  } catch {
+    console.error(`--redis must be a URL like redis://localhost:6379`);
+    process.exit(2);
+  }
+  // Created at boot only when no connection of that name exists yet, so a
+  // second run (or edits made in the UI) never duplicates or overwrites it.
+  env.BULLPANE_CONNECTIONS = JSON.stringify([{ name, url: args.redis, prefix: args.prefix ?? "bull" }]);
+}
+
+await import("../dist/server.mjs");

package/dist/lua/getGroups.lua

@@ -0,0 +1,65 @@
+--[[
+  BullMQ Pro groups, read only. Layout: keys.ts (verified against bullmq-pro 7.48.0).
+
+  KEYS[1]  groups               zset, status "waiting"  (score = round-robin order)
+  KEYS[2]  groups:limit         zset, status "limited"  (score = unix ms the limit lifts)
+  KEYS[3]  groups:max           zset, status "maxed"    (score = unix ms it hit the cap)
+  KEYS[4]  groups:paused        zset, status "paused"   (score = unix ms it was paused)
+  KEYS[5]  groups:active:count  hash  gid -> jobs being processed
+  KEYS[6]  groups:concurrency   hash  gid -> legacy per-group concurrency
+
+  ARGV[1]  start (0-based, inclusive)
+  ARGV[2]  end   (0-based, inclusive; -1 = to the end)
+  ARGV[3]  queue key prefix `${prefix}:${queue}:`
+
+  A group sits in exactly one of the four status zsets, so "all groups" is their
+  concatenation in that order — the same order QueuePro.getGroups pages through.
+  The per-group keys (`groups:${gid}`, `:p`, `:meta`) mirror GROUP_KEY in keys.ts
+  and hang off ARGV[3]: same queue, same hash tag, cluster safe. Everything here
+  is O(1) per group on the page (LLEN / ZCARD / HGET / HMGET).
+
+  Returns { total, { waiting, limited, maxed, paused }, rows } with
+    rows = { { id, status, waiting, prioritized, active, conc|false, lm|false, ld|false, score }, ... }
+  where waiting already includes prioritized.
+]]
+local rcall = redis.call
+local qprefix = ARGV[3]
+local rangeStart = tonumber(ARGV[1])
+local rangeEnd = tonumber(ARGV[2])
+
+local statuses = { "waiting", "limited", "maxed", "paused" }
+local counts = {}
+local total = 0
+for i = 1, 4 do
+  counts[i] = rcall("ZCARD", KEYS[i])
+  total = total + counts[i]
+end
+if rangeEnd < 0 or rangeEnd >= total then rangeEnd = total - 1 end
+
+-- Page across the four zsets as if they were one list: zset i owns the virtual
+-- indices [offset, offset + counts[i] - 1].
+local rows = {}
+local offset = 0
+for i = 1, 4 do
+  local n = counts[i]
+  local last = offset + n - 1
+  if n > 0 and rangeStart <= last and rangeEnd >= offset then
+    local from = math.max(rangeStart, offset) - offset
+    local to = math.min(rangeEnd, last) - offset
+    local raw = rcall("ZRANGE", KEYS[i], from, to, "WITHSCORES")
+    for j = 1, #raw, 2 do
+      local gid = raw[j]
+      local groupKey = qprefix .. "groups:" .. gid
+      local waiting = rcall("LLEN", groupKey)
+      local prioritized = rcall("ZCARD", groupKey .. ":p")
+      local active = tonumber(rcall("HGET", KEYS[5], gid)) or 0
+      local meta = rcall("HMGET", groupKey .. ":meta", "conc", "lm", "ld")
+      -- Pro reads the legacy hash first, then the meta hash (increaseGroupConcurrency.lua).
+      local conc = rcall("HGET", KEYS[6], gid) or meta[1] or false
+      rows[#rows + 1] = { gid, statuses[i], waiting + prioritized, prioritized, active, conc, meta[2] or false, meta[3] or false, raw[j + 1] }
+    end
+  end
+  offset = offset + n
+end
+
+return { total, counts, rows }

package/dist/lua/getJob.lua

@@ -0,0 +1,61 @@
+--[[
+  Full detail of one job in one round trip.
+
+  KEYS[1]      job hash
+  KEYS[2]      `${id}:logs` list
+  KEYS[3]      `${id}:dependencies` set (unprocessed children)
+  KEYS[4]      `${id}:processed` hash (processed children)
+  KEYS[5..12]  state keys in STATE_ORDER:
+               wait, active, completed, failed, delayed, prioritized, paused, waiting-children
+
+  ARGV[1]      job id
+  ARGV[2]      how many log lines (from the tail) to return
+
+  Returns nil when the hash does not exist, otherwise
+    { hgetallFlat, logs, logsCount, dependenciesCount, processedCount, state, delayedScore }
+  `delayedScore` is the job's score in the `delayed` zset (false otherwise):
+  timestamp * 0x1000 + jobId % 0x1000, i.e. when the job becomes runnable.
+
+  State detection: ZSCORE for zsets (O(1)), LPOS for lists (Redis >= 6.0.6,
+  O(N) but in C and without shipping the list). LPOS is wrapped in pcall so an
+  older Redis degrades to "unknown" instead of erroring.
+]]
+local rcall = redis.call
+local jobKey = KEYS[1]
+
+if rcall("EXISTS", jobKey) == 0 then
+  return nil
+end
+
+local hash = rcall("HGETALL", jobKey)
+
+local tail = tonumber(ARGV[2]) or 100
+local logs = rcall("LRANGE", KEYS[2], -tail, -1)
+local logsCount = rcall("LLEN", KEYS[2])
+local depsCount = rcall("SCARD", KEYS[3])
+local processedCount = rcall("HLEN", KEYS[4])
+
+local id = ARGV[1]
+local state = "unknown"
+local delayedScore = false
+
+-- zsets first: cheap and the most common resting states
+local inDelayed = rcall("ZSCORE", KEYS[9], id)
+if rcall("ZSCORE", KEYS[7], id) then state = "completed"
+elseif rcall("ZSCORE", KEYS[8], id) then state = "failed"
+elseif inDelayed then state = "delayed" delayedScore = inDelayed
+elseif rcall("ZSCORE", KEYS[10], id) then state = "prioritized"
+elseif rcall("ZSCORE", KEYS[12], id) then state = "waiting-children"
+else
+  local function inList(key)
+    local ok, pos = pcall(rcall, "LPOS", key, id)
+    if ok and pos then return true end
+    return false
+  end
+  if inList(KEYS[6]) then state = "active"
+  elseif inList(KEYS[5]) then state = "waiting"
+  elseif inList(KEYS[11]) then state = "paused"
+  end
+end
+
+return { hash, logs, logsCount, depsCount, processedCount, state, delayedScore }

package/dist/lua/getJobs.lua

@@ -0,0 +1,156 @@
+--[[
+  One page of job summaries for a state (or a Pro group list) in one round trip.
+
+  KEYS[1]     the state key (list or zset)
+  KEYS[2]     optional, list kind only: a zset whose members come AFTER the list —
+              a Pro group's prioritized jobs (`groups:${gid}:p`), which Pro serves
+              once the group's list is empty (getGroup.lua in bullmq-pro).
+
+  ARGV[1]     "list" | "zset"
+  ARGV[2]     start (0-based, inclusive)
+  ARGV[3]     end   (0-based, inclusive)
+  ARGV[4]     "asc" | "desc"
+  ARGV[5]     queue key prefix `${prefix}:${queue}:` (job hashes live at prefix .. id)
+  ARGV[6]     previewBytes: `data` / `returnvalue` are cut to this many bytes IN REDIS
+  ARGV[7]     maxFieldBytes: a `data` / `returnvalue` field LONGER than this is not
+              read at all (HSTRLEN first, O(1)). HMGET copies the whole field into
+              Lua before we can truncate it, so a page of 200 × 1 MB payloads would
+              block Redis for ~300 ms; with the cap a page costs at most
+              pageSize × maxFieldBytes. The row still carries the size so the UI
+              can say "payload 1.0 MB — open the job".
+  ARGV[8..]   hash fields to HMGET, in the order the caller expects them back
+
+  Returns { total, jobs } where each job is
+    { id, field1, field2, ..., dataTruncated (0|1), dataBytes, score }
+  `score` is the member's zset score (false for lists). For `delayed` it encodes
+  when the job becomes runnable — timestamp * 0x1000 + jobId % 0x1000 — which the
+  hash alone cannot tell after a backoff retry.
+  Hashes that vanished between the range read and the HMGET are skipped.
+
+  Ordering mirrors bullmq's getRanges (queue-getters.js):
+    lists are LPUSHed, so head = newest. desc = LRANGE start end; asc reads from the tail.
+    zsets: desc = ZREVRANGE (highest score = newest), asc = ZRANGE.
+]]
+local rcall = redis.call
+local key = KEYS[1]
+local extra = KEYS[2]
+local kind = ARGV[1]
+local rangeStart = tonumber(ARGV[2])
+local rangeEnd = tonumber(ARGV[3])
+local desc = ARGV[4] ~= "asc"
+local qprefix = ARGV[5]
+local previewBytes = tonumber(ARGV[6])
+local maxFieldBytes = tonumber(ARGV[7])
+
+local fields = {}
+for i = 8, #ARGV do
+  fields[#fields + 1] = ARGV[i]
+end
+-- A field name no job hash has: swapped in for `data` / `returnvalue` when the
+-- real field is over the cap, so the HMGET keeps its shape and returns nil there.
+local SKIP = "\0skip"
+
+-- Positions of the two payload fields we truncate.
+local dataIdx, retIdx = nil, nil
+for i, f in ipairs(fields) do
+  if f == "data" then dataIdx = i end
+  if f == "returnvalue" then retIdx = i end
+end
+
+local function isMarker(id)
+  return string.sub(id, 1, 2) == "0:"
+end
+
+local total
+local ids
+-- id -> raw score string, filled for zsets only
+local scores = {}
+if kind == "list" then
+  total = rcall("LLEN", key)
+  -- legacy marker at the tail is not a job
+  if total > 0 then
+    local last = rcall("LINDEX", key, -1)
+    if last and isMarker(last) then total = total - 1 end
+  end
+  if desc then
+    ids = rcall("LRANGE", key, rangeStart, rangeEnd)
+  else
+    -- asc = oldest first = from the tail. Reverse afterwards.
+    -- Explicit branches: -( -1 + 1 ) is -0 in Lua, which Redis rejects as a non-integer.
+    local fromTail = 0
+    if rangeEnd ~= -1 then fromTail = -(rangeEnd + 1) end
+    local toTail = -1
+    if rangeStart ~= -1 then toTail = -(rangeStart + 1) end
+    local raw = rcall("LRANGE", key, fromTail, toTail)
+    ids = {}
+    for i = #raw, 1, -1 do ids[#ids + 1] = raw[i] end
+  end
+  -- The page runs past the list: continue into the appended zset (ascending score
+  -- = highest priority first, the order Pro will serve them in).
+  if extra then
+    local listTotal = total
+    local extraTotal = rcall("ZCARD", extra)
+    total = listTotal + extraTotal
+    if extraTotal > 0 and (rangeEnd == -1 or rangeEnd >= listTotal) then
+      local from = math.max(0, rangeStart - listTotal)
+      local to = -1
+      if rangeEnd ~= -1 then to = rangeEnd - listTotal end
+      local more = rcall("ZRANGE", extra, from, to)
+      for _, id in ipairs(more) do ids[#ids + 1] = id end
+    end
+  end
+else
+  total = rcall("ZCARD", key)
+  local flat
+  if desc then
+    flat = rcall("ZREVRANGE", key, rangeStart, rangeEnd, "WITHSCORES")
+  else
+    flat = rcall("ZRANGE", key, rangeStart, rangeEnd, "WITHSCORES")
+  end
+  ids = {}
+  for i = 1, #flat, 2 do
+    ids[#ids + 1] = flat[i]
+    scores[flat[i]] = flat[i + 1]
+  end
+end
+
+local jobs = {}
+for _, id in ipairs(ids) do
+  if not isMarker(id) then
+    local hkey = qprefix .. id
+    -- Size first (O(1)); only then decide whether the payload is worth copying.
+    local dataBytes = dataIdx and rcall("HSTRLEN", hkey, "data") or 0
+    local retBytes = retIdx and rcall("HSTRLEN", hkey, "returnvalue") or 0
+    local want = fields
+    if (dataIdx and dataBytes > maxFieldBytes) or (retIdx and retBytes > maxFieldBytes) then
+      want = {}
+      for i = 1, #fields do want[i] = fields[i] end
+      if dataIdx and dataBytes > maxFieldBytes then want[dataIdx] = SKIP end
+      if retIdx and retBytes > maxFieldBytes then want[retIdx] = SKIP end
+    end
+    local vals = rcall("HMGET", hkey, unpack(want))
+    local alive = false
+    for i = 1, #vals do
+      if vals[i] then alive = true break end
+    end
+    if alive then
+      local truncated = 0
+      -- Truncate INSIDE Redis: a 500 KB payload costs the same to render as a tiny one.
+      if dataIdx and dataBytes > previewBytes then
+        if vals[dataIdx] then vals[dataIdx] = string.sub(vals[dataIdx], 1, previewBytes) end
+        truncated = 1
+      end
+      if retIdx and vals[retIdx] and #vals[retIdx] > previewBytes then
+        vals[retIdx] = string.sub(vals[retIdx], 1, previewBytes)
+      end
+      local row = { id }
+      for i = 1, #vals do row[#row + 1] = vals[i] end
+      row[#row + 1] = truncated
+      row[#row + 1] = dataBytes
+      row[#row + 1] = scores[id] or false
+      jobs[#jobs + 1] = row
+    end
+  end
+end
+
+return { total, jobs }

package/dist/lua/getSchedulers.lua

@@ -0,0 +1,76 @@
+--[[
+  Job schedulers ("repeatable jobs") of ONE queue, read only, one round trip.
+
+  Job schedulers do not live in any of the 8 job states. BullMQ keeps them in:
+    `repeat`         zset  schedulerId -> next run (unix ms)
+    `repeat:${id}`   hash  name, pattern | every, tz, offset, limit, ic,
+                           startDate, endDate, data, opts
+  (verified against bullmq 5.81.4 `classes/job-scheduler.js` + a live Redis).
+
+  KEYS[1]   `repeat` zset
+
+  ARGV[1]   start (0-based, inclusive)
+  ARGV[2]   end   (0-based, inclusive)
+  ARGV[3]   queue key prefix `${prefix}:${queue}:` — used to build `repeat:${id}`
+  ARGV[4]   previewBytes: max bytes of `data`/`opts` returned per scheduler
+
+  Returns { total, rows } with
+    rows = { { id, next, name, pattern, every, tz, offset, limit, ic,
+               startDate, endDate, data, opts, truncated }, ... }
+
+  Redis accesses, each justified:
+   1. ZCARD  KEYS[1]                  -> total, for pagination. O(1).
+   2. ZRANGE KEYS[1] start end WITHSCORES
+                                      -> the page, ordered by next run. O(log N + page).
+   3. one HMGET per row on `repeat:${id}`
+                                      -> the scheduler definition. O(1) each, and the
+                                         page size is bounded by the caller (<= 200),
+                                         so this is a bounded fan-out inside a single
+                                         script rather than N round trips.
+  Every key is `${prefix}:${queue}:...`, i.e. the same hash tag: cluster safe.
+
+  `data`/`opts` are truncated HERE (string.sub) so a scheduler stamping out a
+  500 KB template costs the same to list as a tiny one.
+]]
+local rcall = redis.call
+local qprefix = ARGV[3]
+local preview = tonumber(ARGV[4]) or 2048
+
+local total = rcall("ZCARD", KEYS[1])
+local raw = rcall("ZRANGE", KEYS[1], tonumber(ARGV[1]), tonumber(ARGV[2]), "WITHSCORES")
+
+local rows = {}
+for i = 1, #raw, 2 do
+  local id = raw[i]
+  local next_run = raw[i + 1]
+
+  -- HMGET keeps the field order fixed so the caller does not have to parse pairs.
+  -- Field list mirrors SCHEDULER_FIELDS in keys.ts — keep both in sync.
+  local h = rcall(
+    "HMGET", qprefix .. "repeat:" .. id,
+    "name", "pattern", "every", "tz", "offset", "limit", "ic",
+    "startDate", "endDate", "data", "opts"
+  )
+
+  local truncated = 0
+  local data = h[10]
+  if data and #data > preview then
+    data = string.sub(data, 1, preview)
+    truncated = 1
+  end
+  local opts = h[11]
+  if opts and #opts > preview then
+    opts = string.sub(opts, 1, preview)
+    truncated = 1
+  end
+
+  rows[#rows + 1] = {
+    id, next_run,
+    h[1] or false, h[2] or false, h[3] or false, h[4] or false, h[5] or false,
+    h[6] or false, h[7] or false, h[8] or false, h[9] or false,
+    data or false, opts or false,
+    truncated,
+  }
+end
+
+return { total, rows }