hive-am 1.0.0 → 1.2.0

package/server/dist/connections/secrets.js

@@ -0,0 +1,52 @@
+import { connections } from './store.js';
+/**
+ * Last line of defence for text an agent sends to a chat. The instructions tell the agent never to share secrets, but a model can be
+ * talked into it (by anyone in a group, or by an admin who does not realise what the output holds), so the text is checked here
+ * before it leaves this machine. It looks for well-known credential shapes and for the exact secrets this server knows about.
+ * It cannot recognise every secret: it is a net under the rule, not a replacement for it.
+ */
+const SHAPES = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----/, 'a private key'],
+    [/\b\d{8,10}:[A-Za-z0-9_-]{30,}\b/, 'a Telegram bot token'],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/, 'an AWS access key'],
+    [/\bgh[pousr]_[A-Za-z0-9]{30,}\b|\bgithub_pat_[A-Za-z0-9_]{30,}\b/, 'a GitHub token'],
+    [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/, 'a Slack token'],
+    [/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/, 'a Stripe key'],
+    [/\bsk-[A-Za-z0-9_-]{32,}\b/, 'an API key'],
+    [/\bAIza[0-9A-Za-z_-]{35}\b/, 'a Google API key'],
+    [/\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/, 'a JWT'],
+    [/\bBearer\s+[A-Za-z0-9._~+/=-]{24,}/, 'a bearer token'],
+    [/\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s/@]{3,}@[^\s]+/i, 'a URL with a password in it'],
+];
+/** `NAME=value` / `name: value` where the name says it is a secret and the value looks real (not a placeholder). */
+const ASSIGN = /\b([A-Za-z0-9_.-]*(?:password|passwd|pwd|secret|token|api[_-]?key|private[_-]?key|access[_-]?key|credential|auth)[A-Za-z0-9_.-]*)\s*["']?\s*[:=]\s*["']?([^\s"'`,;]{8,})/gi;
+const PLACEHOLDER = /^(<.*>|\{.*\}|\$\{?\w+\}?|\*+|x{4,}|\.{3,}|your[_-]|example|changeme|redacted|none|null|undefined|true|false|process\.env|env\.)/i;
+const SECRET_ENV = /(password|passwd|secret|token|api[_-]?key|private[_-]?key|credential)/i;
+/** Values that are secret because this server holds them: connection tokens and secret-looking environment variables. */
+function knownSecrets() {
+    const out = new Set();
+    for (const c of connections.list())
+        for (const k of ['token', 'signing_secret', 'app_token', 'bot_token']) {
+            const v = c.config?.[k];
+            if (typeof v === 'string' && v.length >= 8)
+                out.add(v);
+        }
+    for (const [k, v] of Object.entries(process.env))
+        if (v && v.length >= 12 && SECRET_ENV.test(k))
+            out.add(v);
+    return [...out];
+}
+/** What kind of secret the text seems to contain, or null when it looks fine. Never returns the secret itself. */
+export function findSecret(text) {
+    for (const s of knownSecrets())
+        if (text.includes(s))
+            return 'a secret held by hive-am or this machine';
+    for (const [re, what] of SHAPES)
+        if (re.test(text))
+            return what;
+    for (const m of text.matchAll(ASSIGN))
+        if (!PLACEHOLDER.test(m[2]))
+            return `the value of "${m[1]}"`;
+    return null;
+}
+export const SECRET_REFUSAL = (what) => `Not sent: the message seems to contain ${what}. Secrets (passwords, tokens, keys, connection strings) are never shared in a chat, not even with an admin or in a private chat. Tell the person you cannot share it and, if it helps, describe where it lives or how they can read it themselves, without writing its value.`;

package/server/dist/connections/store.js

@@ -1,52 +1,13 @@
 import { randomUUID } from 'node:crypto';
 import { db } from '../db.js';
-db.exec(`
-CREATE TABLE IF NOT EXISTS connections (
-  id TEXT PRIMARY KEY, kind TEXT NOT NULL, name TEXT NOT NULL UNIQUE,
-  agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
-  config TEXT NOT NULL DEFAULT '{}', allowed TEXT NOT NULL DEFAULT '[]',
-  enabled INTEGER NOT NULL DEFAULT 1, created_at INTEGER NOT NULL
-);
--- Known threads: where to send a reply and when it was last active. The conversation itself is the agent's one session.
-CREATE TABLE IF NOT EXISTS threads (
-  id TEXT PRIMARY KEY, connection_id TEXT NOT NULL REFERENCES connections(id) ON DELETE CASCADE,
-  external_key TEXT NOT NULL, title TEXT NOT NULL DEFAULT '', target TEXT NOT NULL, last_user TEXT,
-  created_at INTEGER NOT NULL, last_activity INTEGER NOT NULL,
-  UNIQUE (connection_id, external_key)
-);
-CREATE TABLE IF NOT EXISTS thread_messages (
-  id INTEGER PRIMARY KEY AUTOINCREMENT, thread_id TEXT NOT NULL REFERENCES threads(id) ON DELETE CASCADE,
-  direction TEXT NOT NULL, external_id TEXT NOT NULL, user_id TEXT, user_name TEXT,
-  text TEXT NOT NULL, ts INTEGER NOT NULL,
-  UNIQUE (thread_id, direction, external_id)
-);
-CREATE TABLE IF NOT EXISTS connection_cursor (
-  connection_id TEXT PRIMARY KEY REFERENCES connections(id) ON DELETE CASCADE, value TEXT NOT NULL
-);
-`);
-// Columns added after the first release.
-for (const col of ['muted INTEGER NOT NULL DEFAULT 0', 'seen_id INTEGER NOT NULL DEFAULT 0']) {
-    try {
-        db.exec(`ALTER TABLE threads ADD COLUMN ${col}`);
-    }
-    catch { /* already there */ }
-}
-try {
-    db.exec('ALTER TABLE thread_messages ADD COLUMN files TEXT');
-}
-catch { /* already there */ }
+import { parseJson } from '../db/json.js';
+// The tables (connections, threads, thread_messages, connection_cursor) are created by db/migrations.ts.
 const now = () => Date.now();
-const json = (s, fallback) => { try {
-    return JSON.parse(s);
-}
-catch {
-    return fallback;
-} };
 const connRow = (r) => ({
     id: r.id, kind: r.kind, name: r.name, agent_id: r.agent_id,
-    config: json(r.config, {}), allowed: json(r.allowed, []), enabled: !!r.enabled, created_at: r.created_at,
+    config: parseJson(r.config, {}, `connection ${r.id} config`), allowed: parseJson(r.allowed, [], `connection ${r.id} allowed`), enabled: !!r.enabled, created_at: r.created_at,
 });
-const threadRow = (r) => ({ ...r, target: json(r.target, { chat: '' }), muted: !!r.muted, seen_id: r.seen_id ?? 0 });
+const threadRow = (r) => ({ ...r, target: parseJson(r.target, { chat: '' }, `thread ${r.id} target`), muted: !!r.muted, seen_id: r.seen_id ?? 0 });
 export const connections = {
     list: () => db.prepare('SELECT * FROM connections ORDER BY name').all().map(connRow),
     get(id) { const r = db.prepare('SELECT * FROM connections WHERE id=?').get(id); return r ? connRow(r) : undefined; },
@@ -97,6 +58,8 @@ export const threadMessages = {
     /** Remembers the files saved for an inbound message, so they can be listed later as context. */
     setFiles: (threadId, externalId, files) => { db.prepare("UPDATE thread_messages SET files=? WHERE thread_id=? AND direction='in' AND external_id=?").run(JSON.stringify(files), threadId, externalId); },
     /** Id of the newest message of the thread (0 when none). */
+    /** The people who wrote in a thread recently (not the agent). */
+    senders: (threadId) => db.prepare("SELECT DISTINCT user_id AS id, user_name AS name FROM (SELECT user_id, user_name FROM thread_messages WHERE thread_id=? AND direction='in' AND user_name IS NOT NULL ORDER BY id DESC LIMIT 300)").all(threadId),
     lastId: (threadId) => db.prepare('SELECT MAX(id) AS m FROM thread_messages WHERE thread_id=?').get(threadId).m ?? 0,
     /** Messages people wrote that the agent has not been shown yet (after `afterId`, before `beforeId`), oldest first. */
     unseen: (threadId, afterId, beforeId, limit = 30) => db.prepare(`SELECT * FROM (SELECT * FROM thread_messages WHERE thread_id=? AND direction='in' AND id>? AND id<? ORDER BY id DESC LIMIT ?) ORDER BY id`).all(threadId, afterId, beforeId, limit),

package/server/dist/connections/telegram.js

@@ -3,7 +3,10 @@ import { MAX_FILE_BYTES } from './files.js';
 import { mdToTelegramHtml, splitMessage } from './format.js';
 import { cursors } from './store.js';
 const MAX_PART = 3500; // Telegram allows 4096; leave room for the HTML tags added after splitting
+/** The emoji Telegram lets a bot put on a message (Bot API `ReactionTypeEmoji`), without the rude ones (🖕 🤬 💩 🤮 😡). */
+export const TELEGRAM_REACTIONS = ['👍', '👎', '❤', '🔥', '🥰', '👏', '😁', '🤔', '🤯', '😱', '😢', '🎉', '🤩', '🙏', '👌', '🕊', '🤡', '🥱', '🥴', '😍', '🐳', '❤‍🔥', '🌚', '🌭', '💯', '🤣', '⚡', '🍌', '🏆', '💔', '🤨', '😐', '🍓', '🍾', '💋', '😈', '😴', '😭', '🤓', '👻', '👨‍💻', '👀', '🎃', '🙈', '😇', '😨', '🤝', '✍', '🤗', '🫡', '🎅', '🎄', '☃', '💅', '🤪', '🗿', '🆒', '💘', '🙉', '🦄', '😘', '💊', '🙊', '😎', '👾', '🤷', '🤷‍♂', '🤷‍♀'];
 const TYPING_EVERY_MS = 4500; // «typing…» lasts ~5 s
+const TYPING_MAX_MS = 20 * 60_000; // safety net: never pulse for longer than this, whatever happens to the turn
 const MIN_GAP_MS = 350; // stay well under Telegram's ~1 message/second per chat
 const ALBUM_WAIT_MS = 1200; // the photos of an album arrive as separate messages: wait for the rest
 class TelegramError extends Error {
@@ -16,6 +19,13 @@ class TelegramError extends Error {
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const CALL_TIMEOUT_MS = Number(process.env.HIVE_AM_TELEGRAM_TIMEOUT_MS) || 30_000; // a Bot API call that does not answer in this long is a dead connection (a half-open socket never errors by itself)
+const POLL_SLACK_MS = 15_000; // on top of the long-poll wait Telegram is told about
+const UPLOAD_TIMEOUT_MS = 120_000;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/** Aborts when `signal` does or when `ms` pass, whichever comes first. */
+const within = (ms, signal) => (signal ? AbortSignal.any([signal, AbortSignal.timeout(ms)]) : AbortSignal.timeout(ms));
+const timedOut = (e) => e instanceof Error && e.name === 'TimeoutError';
 /** The files of a Telegram message: photos (the biggest size), documents, audio, voice notes, videos and GIFs. Stickers are ignored. */
 function attachmentsOf(msg) {
     const id = String(msg.message_id), out = [];
@@ -52,6 +62,7 @@ export class TelegramAdapter {
     stopped = false;
     abort = new AbortController();
     typing = new Map();
+    typingWarned = 0;
     lastSend = new Map();
     albums = new Map();
     constructor(conn) {
@@ -59,7 +70,14 @@ export class TelegramAdapter {
     }
     get base() { return `${this.conn.config.api_base || 'https://api.telegram.org'}/bot${this.conn.config.token}`; }
     async call(method, body = {}, signal) {
-        const res = await fetch(`${this.base}/${method}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal });
+        const wait = method === 'getUpdates' ? Number(body.timeout ?? 0) * 1000 + POLL_SLACK_MS : CALL_TIMEOUT_MS;
+        let res;
+        try {
+            res = await fetch(`${this.base}/${method}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body), signal: within(wait, signal) });
+        }
+        catch (e) {
+            throw timedOut(e) ? new TelegramError(`Telegram ${method} did not answer in time`, 0) : e;
+        }
         const j = await res.json().catch(() => ({}));
         if (!j.ok)
             throw new TelegramError(j.description ?? `Telegram ${method} failed (${res.status})`, j.error_code ?? res.status, j.parameters?.retry_after);
@@ -82,13 +100,15 @@ export class TelegramAdapter {
         this.stopped = true;
         this.abort.abort();
         for (const t of this.typing.values())
-            clearInterval(t);
+            clearInterval(t.timer);
         this.typing.clear();
         for (const a of this.albums.values())
             clearTimeout(a.timer);
         this.albums.clear();
         this.state = { state: 'stopped' };
     }
+    /** A link to the person's account: it notifies them in a group even without a @username. */
+    mention(u) { return `[${u.name.replace(/[\[\]]/g, '')}](tg://user?id=${u.id})`; }
     status() { return this.state; }
     /** «Connected», with a warning when the connection listens to whole groups but Telegram's privacy mode hides them. */
     connected() {
@@ -153,10 +173,29 @@ export class TelegramAdapter {
         if (cmd && cmd[2] && cmd[2].toLowerCase() !== this.me.username.toLowerCase())
             return null; // a command for another bot
         const mention = new RegExp(`@${this.me.username}\\b`, 'i');
-        const addressed = isPrivate || !!cmd || mention.test(text) || msg.reply_to_message?.from?.id === this.me.id;
+        // In a forum topic every message carries a `reply_to_message` that is just the topic's first message (not a real reply to someone).
+        const realReply = msg.reply_to_message && !msg.reply_to_message.forum_topic_created && !(msg.is_topic_message && msg.reply_to_message.message_id === msg.message_thread_id) ? msg.reply_to_message : undefined;
+        const addressed = isPrivate || !!cmd || mention.test(text) || realReply?.from?.id === this.me.id;
         text = text.replace(mention, '').trim();
         if (!text && !attachments.length)
             return null;
+        // Meant for another person of the chat: a reply to their message, or an @mention / text mention of them.
+        const raw = msg.text ?? msg.caption ?? '';
+        let directedAt;
+        const to = realReply?.from;
+        if (!isPrivate && to && !to.is_bot && to.id !== this.me.id && to.id !== msg.from?.id)
+            directedAt = to.username ?? to.first_name ?? String(to.id);
+        for (const e of (msg.entities ?? msg.caption_entities ?? [])) {
+            if (directedAt || isPrivate)
+                break;
+            if (e.type === 'text_mention' && e.user && !e.user.is_bot && e.user.id !== this.me.id)
+                directedAt = e.user.first_name ?? String(e.user.id);
+            else if (e.type === 'mention') {
+                const u = raw.slice(e.offset + 1, e.offset + e.length);
+                if (u && u.toLowerCase() !== this.me.username.toLowerCase())
+                    directedAt = u;
+            }
+        }
         const topic = msg.is_topic_message && msg.message_thread_id !== undefined ? String(msg.message_thread_id) : undefined;
         const from = msg.from ?? {};
         return {
@@ -170,12 +209,19 @@ export class TelegramAdapter {
             command: cmd ? { name: cmd[1].toLowerCase(), args: (cmd[3] ?? '').trim() } : undefined,
             group: !isPrivate,
             addressed,
+            ...(directedAt ? { directedAt } : {}),
             ...(attachments.length ? { attachments } : {}),
         };
     }
     /** Telegram methods that take a file are multipart, not JSON. */
     async upload(method, form) {
-        const res = await fetch(`${this.base}/${method}`, { method: 'POST', body: form });
+        let res;
+        try {
+            res = await fetch(`${this.base}/${method}`, { method: 'POST', body: form, signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS) });
+        }
+        catch (e) {
+            throw timedOut(e) ? new TelegramError(`Telegram ${method} did not answer in time`, 0) : e;
+        }
         const j = await res.json().catch(() => ({}));
         if (!j.ok)
             throw new TelegramError(j.description ?? `Telegram ${method} failed (${res.status})`, j.error_code ?? res.status, j.parameters?.retry_after);
@@ -216,7 +262,7 @@ export class TelegramAdapter {
         if ((info.file_size ?? 0) > MAX_FILE_BYTES)
             throw new Error('too big (limit 20 MB)');
         const base = this.conn.config.api_base || 'https://api.telegram.org';
-        const res = await fetch(`${base}/file/bot${this.conn.config.token}/${info.file_path}`, { signal: this.abort.signal });
+        const res = await fetch(`${base}/file/bot${this.conn.config.token}/${info.file_path}`, { signal: within(DOWNLOAD_TIMEOUT_MS, this.abort.signal) });
         if (!res.ok)
             throw new Error(`download failed (${res.status})`);
         const buf = Buffer.from(await res.arrayBuffer());
@@ -225,6 +271,24 @@ export class TelegramAdapter {
         writeFileSync(dest, buf);
         return buf.length;
     }
+    /** What a bot may react with on Telegram (the fixed list of the Bot API, minus the rude ones). A group can narrow it further. */
+    reactions = TELEGRAM_REACTIONS;
+    async react(to, ref, emoji) {
+        const wanted = emoji.replace(/\uFE0F/g, '').trim();
+        const emo = TELEGRAM_REACTIONS.find((r) => r.replace(/\uFE0F/g, '') === wanted);
+        if (!emo)
+            throw new Error(`Telegram does not allow “${emoji}” as a reaction. The ones you can use: ${TELEGRAM_REACTIONS.join(' ')}`);
+        if (!ref)
+            throw new Error('There is no message to react to.');
+        try {
+            await this.call('setMessageReaction', { chat_id: to.chat, message_id: Number(ref), reaction: [{ type: 'emoji', emoji: emo }] });
+        }
+        catch (e) {
+            if (e instanceof TelegramError && /REACTION_INVALID|reaction/i.test(e.message))
+                throw new Error(`This chat does not accept ${emo} as a reaction (a group can limit them). Try another one, or answer with text.`);
+            throw e;
+        }
+    }
     async send(to, text) {
         let last = '';
         for (const part of splitMessage(text, MAX_PART)) {
@@ -236,6 +300,8 @@ export class TelegramAdapter {
             }));
             last = String(sent.message_id);
         }
+        if (this.typing.has(`${to.chat}:${to.thread ?? ''}`))
+            this.ping(to); // a sent message cancels «typing…»; the agent is still working
         return { externalId: last };
     }
     /** Keeps one chat's messages spaced out and honours Telegram's `retry_after` when it pushes back. */
@@ -257,18 +323,43 @@ export class TelegramAdapter {
             }
         }
     }
-    async busy(to, state) {
+    /** One «typing…» pulse. A failure is logged (once a minute) instead of being swallowed, so a silent problem is visible. */
+    ping(to) {
+        void this.call('sendChatAction', { chat_id: to.chat, action: 'typing', ...(to.thread ? { message_thread_id: Number(to.thread) } : {}) }).catch((e) => {
+            if (Date.now() - this.typingWarned > 60_000) {
+                this.typingWarned = Date.now();
+                console.warn(`[connections] ${this.conn.name}: «typing…» failed: ${e.message}`);
+            }
+        });
+    }
+    async busy(to, state, ref = '') {
         const key = `${to.chat}:${to.thread ?? ''}`;
-        const old = this.typing.get(key);
-        if (old) {
-            clearInterval(old);
-            this.typing.delete(key);
+        const cur = this.typing.get(key);
+        if (state === 'working') {
+            if (cur) {
+                cur.refs.add(ref);
+                return;
+            }
+            this.ping(to);
+            const since = Date.now();
+            const timer = setInterval(() => {
+                if (Date.now() - since > TYPING_MAX_MS) {
+                    clearInterval(timer);
+                    this.typing.delete(key);
+                    return;
+                }
+                this.ping(to);
+            }, TYPING_EVERY_MS);
+            this.typing.set(key, { timer, refs: new Set([ref]) });
+            return;
         }
-        if (state !== 'working')
+        if (!cur)
             return;
-        const ping = () => void this.call('sendChatAction', { chat_id: to.chat, action: 'typing', ...(to.thread ? { message_thread_id: Number(to.thread) } : {}) }).catch(() => undefined);
-        ping();
-        this.typing.set(key, setInterval(ping, TYPING_EVERY_MS));
+        cur.refs.delete(ref);
+        if (!cur.refs.size) {
+            clearInterval(cur.timer);
+            this.typing.delete(key);
+        }
     }
     async test(userIds) {
         const me = await this.call('getMe');

package/server/dist/cron.js

@@ -0,0 +1,138 @@
+import { DomainError } from './errors.js';
+/**
+ * Cron expressions (5 fields: minute hour day-of-month month day-of-week) evaluated in a time zone.
+ * The next run is computed from calendar days and local times and then mapped to an instant, so daylight-saving changes behave:
+ * a local time that does not exist (the hour skipped in spring) is skipped, and one that happens twice (autumn) runs once, the first time.
+ */
+export class CronError extends DomainError {
+}
+const NAMES = {
+    month: { JAN: 1, FEB: 2, MAR: 3, APR: 4, MAY: 5, JUN: 6, JUL: 7, AUG: 8, SEP: 9, OCT: 10, NOV: 11, DEC: 12 },
+    dow: { SUN: 0, MON: 1, TUE: 2, WED: 3, THU: 4, FRI: 5, SAT: 6 },
+};
+const MACROS = { '@hourly': '0 * * * *', '@daily': '0 0 * * *', '@midnight': '0 0 * * *', '@weekly': '0 0 * * 0', '@monthly': '0 0 1 * *' };
+function field(src, min, max, names) {
+    const num = (s) => {
+        const v = names?.[s.toUpperCase()] ?? (/^\d+$/.test(s) ? Number(s) : NaN);
+        if (!Number.isInteger(v) || v < min || v > max)
+            throw new CronError(`"${s}" is out of range (${min}-${max})`);
+        return v;
+    };
+    const out = new Set();
+    let any = false;
+    for (const part of src.split(',')) {
+        const [range, stepText] = part.split('/');
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1)
+            throw new CronError(`Invalid step "${stepText}"`);
+        let from, to;
+        if (range === '*' || range === '?') {
+            from = min;
+            to = max;
+            if (stepText === undefined)
+                any = true;
+        }
+        else if (range.includes('-')) {
+            const [a, b] = range.split('-');
+            from = num(a);
+            to = num(b);
+            if (from > to)
+                throw new CronError(`Range ${range} goes backwards`);
+        }
+        else {
+            from = num(range);
+            to = stepText === undefined ? from : max;
+        }
+        for (let v = from; v <= to; v += step)
+            out.add(v);
+    }
+    return { values: [...out].sort((a, b) => a - b), any };
+}
+export function parseCron(expression) {
+    const text = MACROS[expression.trim().toLowerCase()] ?? expression.trim();
+    const parts = text.split(/\s+/);
+    if (parts.length !== 5)
+        throw new CronError('A cron expression has 5 fields: minute hour day-of-month month day-of-week (for example "0 9 * * MON-FRI")');
+    const minute = field(parts[0], 0, 59), hour = field(parts[1], 0, 23), dom = field(parts[2], 1, 31), month = field(parts[3], 1, 12, NAMES.month);
+    const dowRaw = field(parts[4].replace(/\b7\b/g, '0'), 0, 6, NAMES.dow);
+    return { minute: minute.values, hour: hour.values, dom: dom.values, month: month.values, dow: dowRaw.values, domAny: dom.any, dowAny: dowRaw.any };
+}
+// ---- time zones ----
+const formats = new Map();
+function format(tz) {
+    let f = formats.get(tz);
+    if (!f) {
+        f = new Intl.DateTimeFormat('en-US', { timeZone: tz, hourCycle: 'h23', year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric' });
+        formats.set(tz, f);
+    }
+    return f;
+}
+export function validTimezone(tz) { try {
+    format(tz);
+    return true;
+}
+catch {
+    return false;
+} }
+export const serverTimezone = () => Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+function local(ts, tz) {
+    const p = {};
+    for (const x of format(tz).formatToParts(new Date(ts)))
+        if (x.type !== 'literal')
+            p[x.type] = Number(x.value);
+    return { y: p.year, m: p.month, d: p.day, h: p.hour % 24, mi: p.minute, s: p.second };
+}
+const offsetMs = (ts, tz) => { const l = local(ts, tz); return Date.UTC(l.y, l.m - 1, l.d, l.h, l.mi, l.s) - Math.floor(ts / 1000) * 1000; };
+/** The instant at which the wall clock of `tz` reads y-m-d h:mi, or null when that time does not exist there (spring-forward gap). */
+function zonedToUtc(y, m, d, h, mi, tz) {
+    const wall = Date.UTC(y, m - 1, d, h, mi);
+    let utc = wall - offsetMs(wall, tz);
+    utc = wall - offsetMs(utc, tz); // second pass: the offset may differ at the new instant
+    const l = local(utc, tz);
+    return l.y === y && l.m === m && l.d === d && l.h === h && l.mi === mi ? utc : null;
+}
+/** First run strictly after `after` (ms), or null if there is none in the next 8 years. */
+export function nextCron(expression, tz, after) {
+    const spec = typeof expression === 'string' ? parseCron(expression) : expression;
+    const start = local(after, tz);
+    for (let k = 0; k < 366 * 8; k++) {
+        const day = new Date(Date.UTC(start.y, start.m - 1, start.d + k));
+        const y = day.getUTCFullYear(), m = day.getUTCMonth() + 1, d = day.getUTCDate(), wd = day.getUTCDay();
+        if (!spec.month.includes(m))
+            continue;
+        const domOk = spec.dom.includes(d), dowOk = spec.dow.includes(wd);
+        const dayOk = spec.domAny || spec.dowAny ? domOk && dowOk : domOk || dowOk; // both restricted: either matches (classic cron)
+        if (!dayOk)
+            continue;
+        for (const h of spec.hour)
+            for (const mi of spec.minute) {
+                const t = zonedToUtc(y, m, d, h, mi, tz);
+                if (t !== null && t > after)
+                    return t;
+            }
+    }
+    return null;
+}
+/** The next `count` runs. */
+export function nextRuns(expression, tz, after, count) {
+    const spec = parseCron(expression), out = [];
+    let t = after;
+    while (out.length < count) {
+        const n = nextCron(spec, tz, t);
+        if (n === null)
+            break;
+        out.push(n);
+        t = n;
+    }
+    return out;
+}
+/** Smallest gap, in minutes, between the next runs: protects against "* * * * *" and the like. */
+export function minGapMinutes(expression, tz, after) {
+    const runs = nextRuns(expression, tz, after, 12);
+    if (runs.length < 2)
+        return Infinity;
+    let min = Infinity;
+    for (let i = 1; i < runs.length; i++)
+        min = Math.min(min, (runs[i] - runs[i - 1]) / 60000);
+    return min;
+}

package/server/dist/db/json.js

@@ -0,0 +1,16 @@
+/** JSON.parse for a column or a file that may be damaged: the fallback is used (and the problem is logged once per label) instead of throwing into a request. */
+const warned = new Set();
+export function parseJson(raw, fallback, label = 'json') {
+    if (raw === null || raw === undefined || raw === '')
+        return fallback;
+    try {
+        return JSON.parse(String(raw));
+    }
+    catch (e) {
+        if (!warned.has(label)) {
+            warned.add(label);
+            console.warn(`[db] ${label}: unreadable JSON, using a default (${e instanceof Error ? e.message : e})`);
+        }
+        return fallback;
+    }
+}