@spinabot/brigade 0.1.2 → 1.0.1

package/dist/cron/reminder-context.js

@@ -0,0 +1,167 @@
+/**
+ * Reminder-context helper for cron `systemEvent` payloads.
+ *
+ * When the agent (via the cron tool) schedules a reminder with
+ * `contextMessages: N`, this module fetches the caller's last N messages from
+ * the gateway's session history and formats them into a compact
+ * `Recent context:` block appended to the reminder's text. The fire-time
+ * heartbeat consumer sees the operator's recent chat alongside the reminder
+ * so the reply can pick up on what they were just talking about.
+ *
+ * Constants are tuned for tight budgets — the reminder text itself is the
+ * primary signal; the context is a hint. Total context never exceeds 700
+ * chars across at most 10 lines of at most 220 chars each.
+ *
+ * Mirrored from the upstream cron-tool reminder-context block. Two small
+ * Brigade-side adjustments:
+ *   1. Calls `sessions.history` (Brigade's RPC) instead of `chat.history`.
+ *   2. Drops the public-alias → internal-key resolver step because Brigade
+ *      session keys are already in internal form. Caller passes the key as-
+ *      is; `handleSessionsHistory` accepts it directly.
+ */
+import { callGateway } from "../agents/gateway-call.js";
+export const REMINDER_CONTEXT_MESSAGES_MAX = 10;
+export const REMINDER_CONTEXT_PER_MESSAGE_MAX = 220;
+export const REMINDER_CONTEXT_TOTAL_MAX = 700;
+export const REMINDER_CONTEXT_MARKER = "\n\nRecent context:\n";
+/**
+ * Strip a previously-appended `Recent context:` block so a re-add (e.g.
+ * follow-up `cron update`) doesn't double-stack contexts. Idempotent.
+ */
+export function stripExistingContext(text) {
+    const index = text.indexOf(REMINDER_CONTEXT_MARKER);
+    if (index === -1)
+        return text;
+    return text.slice(0, index).trim();
+}
+/** UTF-16-safe truncation with "..." suffix when over `maxLen`. */
+export function truncateText(input, maxLen) {
+    if (input.length <= maxLen)
+        return input;
+    const headLen = Math.max(0, maxLen - 3);
+    // Don't split a surrogate pair: if the last code unit is a high
+    // surrogate, drop one more code unit.
+    let head = input.slice(0, headLen);
+    if (head.length > 0) {
+        const last = head.charCodeAt(head.length - 1);
+        if (last >= 0xd800 && last <= 0xdbff) {
+            head = head.slice(0, -1);
+        }
+    }
+    return `${head.trimEnd()}...`;
+}
+/**
+ * Pull `text` out of a chat message's `content` field. Handles both legacy
+ * string-content and the Anthropic-style array-of-blocks. Returns `null` for
+ * non-text content or whitespace-only text so the caller can drop the entry.
+ */
+export function extractTextFromChatContent(content) {
+    if (typeof content === "string") {
+        const trimmed = content.replace(/\s+/g, " ").trim();
+        return trimmed ? trimmed : null;
+    }
+    if (Array.isArray(content)) {
+        const parts = [];
+        for (const block of content) {
+            if (!block || typeof block !== "object")
+                continue;
+            const rec = block;
+            if (rec.type !== "text")
+                continue;
+            if (typeof rec.text !== "string")
+                continue;
+            parts.push(rec.text);
+        }
+        const joined = parts.join(" ").replace(/\s+/g, " ").trim();
+        return joined ? joined : null;
+    }
+    return null;
+}
+function extractMessageText(message) {
+    const role = typeof message.role === "string" ? message.role : "";
+    if (role !== "user" && role !== "assistant")
+        return null;
+    const text = extractTextFromChatContent(message.content);
+    return text ? { role, text } : null;
+}
+/**
+ * Build the `- Role: text` lines for the `Recent context:` block.
+ *
+ * Returns `[]` when:
+ *   - `contextMessages <= 0` after clamping.
+ *   - `agentSessionKey` is empty / whitespace (TUI / standalone CLI).
+ *   - The gateway call throws (any reason — silent degrade, the reminder
+ *     still fires without context).
+ *
+ * Respects both per-message (220 chars + "...") and total (700 chars) caps;
+ * the first line that would push total over budget is dropped (not
+ * partially included).
+ */
+export async function buildReminderContextLines(opts) {
+    const maxMessages = Math.min(REMINDER_CONTEXT_MESSAGES_MAX, Math.max(0, Math.floor(opts.contextMessages)));
+    if (maxMessages <= 0)
+        return [];
+    const sessionKey = opts.agentSessionKey?.trim();
+    if (!sessionKey)
+        return [];
+    const dispatch = opts.callGateway ?? callGateway;
+    try {
+        const res = await dispatch({
+            method: "sessions.history",
+            params: { sessionKey, limit: maxMessages },
+        });
+        const messages = Array.isArray(res?.messages) ? res.messages : [];
+        const parsed = messages
+            .map((m) => extractMessageText(m))
+            .filter((m) => Boolean(m));
+        const recent = parsed.slice(-maxMessages);
+        if (recent.length === 0)
+            return [];
+        const lines = [];
+        let total = 0;
+        for (const entry of recent) {
+            const label = entry.role === "user" ? "User" : "Assistant";
+            const text = truncateText(entry.text, REMINDER_CONTEXT_PER_MESSAGE_MAX);
+            const line = `- ${label}: ${text}`;
+            total += line.length;
+            if (total > REMINDER_CONTEXT_TOTAL_MAX)
+                break;
+            lines.push(line);
+        }
+        return lines;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Mutate-or-passthrough helper used by the cron tool's `add` branch.
+ * When the input job's payload is a non-empty `systemEvent.text`, fetches
+ * recent context and appends it to the payload's text. Non-mutating: returns
+ * the original input when context can't be built.
+ */
+export async function maybeAttachReminderContext(args) {
+    const payloadRaw = args.job.payload;
+    if (!payloadRaw || typeof payloadRaw !== "object" || Array.isArray(payloadRaw)) {
+        return args.job;
+    }
+    const payload = payloadRaw;
+    if (payload.kind !== "systemEvent")
+        return args.job;
+    if (typeof payload.text !== "string" || !payload.text.trim())
+        return args.job;
+    const lines = await buildReminderContextLines({
+        contextMessages: args.contextMessages,
+        ...(args.agentSessionKey !== undefined ? { agentSessionKey: args.agentSessionKey } : {}),
+        ...(args.callGateway !== undefined ? { callGateway: args.callGateway } : {}),
+    });
+    if (lines.length === 0)
+        return args.job;
+    const baseText = stripExistingContext(payload.text);
+    const nextText = `${baseText}${REMINDER_CONTEXT_MARKER}${lines.join("\n")}`;
+    return {
+        ...args.job,
+        payload: { ...payload, text: nextText },
+    };
+}
+//# sourceMappingURL=reminder-context.js.map

package/dist/cron/reminder-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-context.js","sourceRoot":"","sources":["../../src/cron/reminder-context.ts"],"names":[],"mappings":"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"}

package/dist/cron/run-log.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cron run history — one JSONL file per job at
+ * `~/.brigade/cron/runs/<jobId>.jsonl`.
+ *
+ * Append-only on every finished run. Pruned in-place when the file crosses
+ * either of two caps:
+ *   - byte size (default 2 MB)
+ *   - line count (default 2000)
+ *
+ * On prune, we keep the TAIL — the newest entries are the ones the operator
+ * actually cares about ("did my nightly backup run last night?"). Older
+ * entries get dropped silently.
+ *
+ * The pruner reads the whole file into memory before rewriting; given the
+ * 2 MB cap that's a one-shot tens-of-milliseconds operation on any modern
+ * disk. We don't bother with rotated-file archives — the operator wants a
+ * single fresh view, not a history of pruned chunks.
+ */
+import type { CronRunLogEntry } from "./types.js";
+export declare const DEFAULT_CRON_RUN_LOG_MAX_BYTES = 2000000;
+export declare const DEFAULT_CRON_RUN_LOG_KEEP_LINES = 2000;
+export interface CronRunLogLimits {
+    maxBytes?: number;
+    keepLines?: number;
+}
+/** Path to the run-log directory: `~/.brigade/cron/runs/`. */
+export declare function resolveCronRunLogDir(): string;
+/** Path to the per-job run-log file. Throws on a malformed / traversal jobId. */
+export declare function resolveCronRunLogPath(jobId: string): string;
+/**
+ * Append one `CronRunLogEntry` to the per-job JSONL. Best-effort: if the
+ * filesystem is full or unwritable, we log a warning and return — the run's
+ * actual outcome (in the cron event + the task ledger) is the authoritative
+ * record. The log file is for human-facing forensics, not for correctness.
+ */
+export declare function appendCronRunLog(entry: CronRunLogEntry, limits?: CronRunLogLimits): Promise<void>;
+export interface ReadCronRunLogOpts {
+    limit?: number;
+    offset?: number;
+    status?: "ok" | "error" | "skipped";
+}
+/**
+ * Read run history entries newest-first. Returns up to `limit` entries
+ * starting at `offset`. Filters by `status` when supplied. Missing file →
+ * empty result (treated as "no runs yet").
+ */
+export declare function readCronRunLogEntries(jobId: string, opts?: ReadCronRunLogOpts): Promise<CronRunLogEntry[]>;
+//# sourceMappingURL=run-log.d.ts.map

package/dist/cron/run-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-log.d.ts","sourceRoot":"","sources":["../../src/cron/run-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,eAAO,MAAM,8BAA8B,UAAY,CAAC;AACxD,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAmBD,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAaD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACrC,KAAK,EAAE,eAAe,EACtB,MAAM,CAAC,EAAE,gBAAgB,GACvB,OAAO,CAAC,IAAI,CAAC,CA2Cf;AA+CD,MAAM,WAAW,kBAAkB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAC1C,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,kBAAuB,GAC3B,OAAO,CAAC,eAAe,EAAE,CAAC,CAoD5B"}

package/dist/cron/run-log.js

@@ -0,0 +1,225 @@
+/**
+ * Cron run history — one JSONL file per job at
+ * `~/.brigade/cron/runs/<jobId>.jsonl`.
+ *
+ * Append-only on every finished run. Pruned in-place when the file crosses
+ * either of two caps:
+ *   - byte size (default 2 MB)
+ *   - line count (default 2000)
+ *
+ * On prune, we keep the TAIL — the newest entries are the ones the operator
+ * actually cares about ("did my nightly backup run last night?"). Older
+ * entries get dropped silently.
+ *
+ * The pruner reads the whole file into memory before rewriting; given the
+ * 2 MB cap that's a one-shot tens-of-milliseconds operation on any modern
+ * disk. We don't bother with rotated-file archives — the operator wants a
+ * single fresh view, not a history of pruned chunks.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../config/paths.js";
+import { renameWithRetryAsync } from "../infra/fs/atomic-rename.js";
+import { createSubsystemLogger } from "../logging/subsystem-logger.js";
+import { tryGetRuntimeContext } from "../storage/runtime-context.js";
+const log = createSubsystemLogger("cron/runs");
+export const DEFAULT_CRON_RUN_LOG_MAX_BYTES = 2_000_000;
+export const DEFAULT_CRON_RUN_LOG_KEEP_LINES = 2000;
+/** Path to the run-log directory: `~/.brigade/cron/runs/`. */
+export function resolveCronRunLogDir() {
+    return path.join(resolveStateDir(), "cron", "runs");
+}
+/**
+ * Guard against `..` / `/` / `\` / NUL in the jobId so a malicious or
+ * malformed id can never write OUTSIDE the runs/ directory. Lifted from
+ * the reference architecture (src/cron/run-log.ts:58-79); we keep the
+ * exact same `resolvedPath.startsWith(runsDir + sep)` re-validation as
+ * the belt-and-braces layer in case the trimmed id still resolves out
+ * of bounds on some exotic filesystem.
+ */
+function assertSafeCronRunLogJobId(jobId) {
+    const trimmed = jobId.trim();
+    if (!trimmed)
+        throw new Error("invalid cron run log job id");
+    if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("\0")) {
+        throw new Error("invalid cron run log job id");
+    }
+    return trimmed;
+}
+/** Path to the per-job run-log file. Throws on a malformed / traversal jobId. */
+export function resolveCronRunLogPath(jobId) {
+    const runsDir = path.resolve(resolveCronRunLogDir());
+    const safeJobId = assertSafeCronRunLogJobId(jobId);
+    const resolvedPath = path.resolve(runsDir, `${safeJobId}.jsonl`);
+    if (!resolvedPath.startsWith(`${runsDir}${path.sep}`)) {
+        throw new Error("invalid cron run log job id");
+    }
+    return resolvedPath;
+}
+/**
+ * Best-effort chmod helper for the per-job JSONL file. Cron schedules can
+ * contain sensitive operator context (reminder text, recent message
+ * snippets) so the run history mirror the store's 0o600 posture. Windows
+ * doesn't honour POSIX modes — the chmod swallows there and the file
+ * keeps its NTFS ACL.
+ */
+async function setSecureRunLogFileMode(filePath) {
+    await fs.chmod(filePath, 0o600).catch(() => undefined);
+}
+/**
+ * Append one `CronRunLogEntry` to the per-job JSONL. Best-effort: if the
+ * filesystem is full or unwritable, we log a warning and return — the run's
+ * actual outcome (in the cron event + the task ledger) is the authoritative
+ * record. The log file is for human-facing forensics, not for correctness.
+ */
+export async function appendCronRunLog(entry, limits) {
+    // Convex mode — one row per run event in the cronRuns table; retention
+    // is the backend's concern (no per-file prune).
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        try {
+            await rctx.store.cron.appendRunLog(entry);
+        }
+        catch (err) {
+            log.warn("append to convex failed — run history may be missing this entry", {
+                jobId: entry.jobId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return;
+    }
+    const dir = resolveCronRunLogDir();
+    let filePath;
+    try {
+        filePath = resolveCronRunLogPath(entry.jobId);
+    }
+    catch (err) {
+        log.warn("append rejected — jobId failed traversal guard", {
+            jobId: entry.jobId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    try {
+        // `mode: 0o700` on the run-log dir mirrors the store's posix posture
+        // so sibling users on a shared box can't enumerate the operator's
+        // cron job ids by listing the runs/ directory.
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        const line = `${JSON.stringify(entry)}\n`;
+        await fs.appendFile(filePath, line, "utf8");
+        // Tighten perms after the append (Linux/macOS); Windows swallows.
+        await setSecureRunLogFileMode(filePath);
+        await maybePruneCronRunLog(filePath, limits);
+    }
+    catch (err) {
+        log.warn("append failed — run history may be missing this entry", {
+            jobId: entry.jobId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Tail-retain prune: if the file is over either cap, drop the oldest lines
+ * until we're back under both. Idempotent — when neither cap is exceeded
+ * we never even read the file.
+ */
+async function maybePruneCronRunLog(filePath, limits) {
+    const maxBytes = limits?.maxBytes ?? DEFAULT_CRON_RUN_LOG_MAX_BYTES;
+    const keepLines = limits?.keepLines ?? DEFAULT_CRON_RUN_LOG_KEEP_LINES;
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    }
+    catch {
+        return; // file vanished mid-flight — nothing to prune
+    }
+    if (stat.size <= maxBytes) {
+        // Still need to check line count even if bytes are under cap, but
+        // the line count usually correlates so this is the common short-
+        // circuit path.
+        const raw = await fs.readFile(filePath, "utf8");
+        const lines = raw.split("\n").filter((l) => l.length > 0);
+        if (lines.length <= keepLines)
+            return;
+        const keep = lines.slice(-keepLines);
+        await atomicReplace(filePath, `${keep.join("\n")}\n`);
+        return;
+    }
+    const raw = await fs.readFile(filePath, "utf8");
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    const sliceFrom = Math.max(0, lines.length - keepLines);
+    const kept = lines.slice(sliceFrom);
+    await atomicReplace(filePath, `${kept.join("\n")}\n`);
+}
+/** Atomic rewrite via tmp + rename so a crash mid-prune doesn't lose data. */
+async function atomicReplace(filePath, contents) {
+    const tmp = `${filePath}.tmp`;
+    await fs.writeFile(tmp, contents, "utf8");
+    // Retry rename for the Windows EPERM/EBUSY window — same defence the
+    // cron store uses on its tmp+rename hot path.
+    await renameWithRetryAsync(tmp, filePath);
+    await setSecureRunLogFileMode(filePath);
+}
+/**
+ * Read run history entries newest-first. Returns up to `limit` entries
+ * starting at `offset`. Filters by `status` when supplied. Missing file →
+ * empty result (treated as "no runs yet").
+ */
+export async function readCronRunLogEntries(jobId, opts = {}) {
+    // Convex mode — newest-first query against cronRuns. The status filter +
+    // offset/limit window are applied here so both modes return identical
+    // shapes for identical inputs.
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        try {
+            const limit = Math.max(0, opts.limit ?? 50);
+            const offset = Math.max(0, opts.offset ?? 0);
+            const rows = (await rctx.store.cron.listRunLog(jobId, {
+                limit: offset + limit + (opts.status !== undefined ? 200 : 0),
+            }));
+            const filtered = opts.status !== undefined ? rows.filter((r) => r.status === opts.status) : rows;
+            return filtered.slice(offset, offset + limit);
+        }
+        catch {
+            return [];
+        }
+    }
+    // Path-traversal guard applies on read too — a malformed jobId from a
+    // caller that bypassed the store should still be rejected.
+    let filePath;
+    try {
+        filePath = resolveCronRunLogPath(jobId);
+    }
+    catch {
+        return [];
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const limit = Math.max(0, opts.limit ?? 50);
+    const offset = Math.max(0, opts.offset ?? 0);
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    const decoded = [];
+    // Iterate newest-first by walking the array in reverse.
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (opts.status !== undefined && parsed.status !== opts.status)
+            continue;
+        decoded.push(parsed);
+        if (decoded.length >= offset + limit)
+            break;
+    }
+    return decoded.slice(offset, offset + limit);
+}
+//# sourceMappingURL=run-log.js.map

package/dist/cron/run-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-log.js","sourceRoot":"","sources":["../../src/cron/run-log.ts"],"names":[],"mappings":"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"}

package/dist/cron/schedule.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Schedule resolver — turns a `CronSchedule` plus current time into a next-
+ * fire timestamp.
+ *
+ * Three kinds, three algorithms:
+ *
+ *   - `cron` → delegate to the `croner` library (5/6/7-field with named
+ *     months/days). Per-expression timezone supported; falls back to the
+ *     host timezone via `Intl.DateTimeFormat().resolvedOptions().timeZone`
+ *     when unset. `catch: false` means missed DST-gap times are skipped
+ *     (NOT caught up) — the next valid fire is the next non-ambiguous slot.
+ *   - `every` → arithmetic: nextRun = anchor + ceil((now - anchor) / step) * step.
+ *   - `at` → return the timestamp if it's in the future, else undefined
+ *     (one-shot is done).
+ *
+ * Parsing is expensive enough to be worth caching — the LRU keyed on
+ * `<expr>::<tz>` holds the last 512 parsed Cron instances. Cache misses
+ * happen on every-job-changes events; cache hits are the steady-state.
+ */
+import type { CronSchedule } from "./types.js";
+/**
+ * Throws on an invalid cron expression. Operator-facing — message comes from
+ * croner directly and is already reasonable ("Pattern A of the expression is
+ * invalid").
+ */
+export declare function validateCronExpression(expr: string, tz?: string): void;
+/**
+ * Compute the next-fire timestamp for a schedule, given the current
+ * wall-clock time. Returns `undefined` when the schedule has no future fires
+ * (one-shot `at` already passed) — caller treats that as "job is done".
+ */
+export declare function computeNextRunAtMs(schedule: CronSchedule, nowMs: number): number | undefined;
+/**
+ * Compute the PREVIOUS fire-time at or before `nowMs`. Used for catchup
+ * detection: when the process restarts after a gap, we ask "what was the
+ * most recent scheduled slot?" and compare to `lastRunAtMs` to decide
+ * whether to replay.
+ *
+ * Only meaningful for `cron` + `every` kinds. `at` jobs are one-shot — if
+ * they fired, `lastRunAtMs` is set; if not, the catchup logic will simply
+ * fire them on the next tick.
+ */
+export declare function computePreviousRunAtMs(schedule: CronSchedule, nowMs: number): number | undefined;
+/** Test-only hook: clear the LRU between cases. */
+export declare function clearScheduleCacheForTests(): void;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/cron/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/cron/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8B/C;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAqCpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,YAAY,EACtB,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAwBpB;AAED,mDAAmD;AACnD,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/cron/schedule.js

@@ -0,0 +1,144 @@
+/**
+ * Schedule resolver — turns a `CronSchedule` plus current time into a next-
+ * fire timestamp.
+ *
+ * Three kinds, three algorithms:
+ *
+ *   - `cron` → delegate to the `croner` library (5/6/7-field with named
+ *     months/days). Per-expression timezone supported; falls back to the
+ *     host timezone via `Intl.DateTimeFormat().resolvedOptions().timeZone`
+ *     when unset. `catch: false` means missed DST-gap times are skipped
+ *     (NOT caught up) — the next valid fire is the next non-ambiguous slot.
+ *   - `every` → arithmetic: nextRun = anchor + ceil((now - anchor) / step) * step.
+ *   - `at` → return the timestamp if it's in the future, else undefined
+ *     (one-shot is done).
+ *
+ * Parsing is expensive enough to be worth caching — the LRU keyed on
+ * `<expr>::<tz>` holds the last 512 parsed Cron instances. Cache misses
+ * happen on every-job-changes events; cache hits are the steady-state.
+ */
+import { Cron } from "croner";
+const PARSE_CACHE_MAX = 512;
+const parseCache = new Map();
+function resolveCronTimezone(tz) {
+    if (typeof tz === "string" && tz.length > 0)
+        return tz;
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+function getOrParseCron(expr, tz) {
+    const cacheKey = `${expr}::${tz}`;
+    const cached = parseCache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    // `catch: false` propagates parse errors to the caller instead of
+    // silently producing a no-fire instance — we want the operator (or the
+    // agent that called `cron add`) to see a clear validation error.
+    const parsed = new Cron(expr, { timezone: tz, catch: false });
+    if (parseCache.size >= PARSE_CACHE_MAX) {
+        const oldest = parseCache.keys().next().value;
+        if (oldest !== undefined)
+            parseCache.delete(oldest);
+    }
+    parseCache.set(cacheKey, parsed);
+    return parsed;
+}
+/**
+ * Throws on an invalid cron expression. Operator-facing — message comes from
+ * croner directly and is already reasonable ("Pattern A of the expression is
+ * invalid").
+ */
+export function validateCronExpression(expr, tz) {
+    getOrParseCron(expr, resolveCronTimezone(tz));
+}
+/**
+ * Compute the next-fire timestamp for a schedule, given the current
+ * wall-clock time. Returns `undefined` when the schedule has no future fires
+ * (one-shot `at` already passed) — caller treats that as "job is done".
+ */
+export function computeNextRunAtMs(schedule, nowMs) {
+    switch (schedule.kind) {
+        case "at": {
+            return schedule.at > nowMs ? schedule.at : undefined;
+        }
+        case "every": {
+            const step = Math.max(1, Math.floor(schedule.everyMs));
+            const anchor = schedule.anchorMs ?? nowMs;
+            // Future anchor — first fire IS the anchor itself.
+            if (nowMs < anchor)
+                return anchor;
+            // Strict "next slot AFTER nowMs": adding 1 to the floor ensures
+            // `nowMs == anchor` (the common case for fresh jobs) advances by
+            // one interval rather than firing immediately. Operators who say
+            // `every 5m` expect the first fire 5 minutes out, not right now.
+            const elapsed = nowMs - anchor;
+            const steps = Math.floor(elapsed / step) + 1;
+            return anchor + steps * step;
+        }
+        case "cron": {
+            const tz = resolveCronTimezone(schedule.tz);
+            const cron = getOrParseCron(schedule.expr, tz);
+            const next = cron.nextRun(new Date(nowMs));
+            if (!next)
+                return undefined;
+            const nextMs = next.getTime();
+            // Defensive: croner has historically had edge-case bugs around
+            // year boundaries in some timezones (e.g., it would suggest a
+            // "next run" that's actually in the past). If we see that, nudge
+            // the seed forward and retry once — covers the bug without
+            // pinning to a specific croner patch level.
+            if (nextMs <= nowMs) {
+                const retry = cron.nextRun(new Date(nowMs + 1000));
+                if (retry && retry.getTime() > nowMs)
+                    return retry.getTime();
+                return undefined;
+            }
+            return nextMs;
+        }
+    }
+}
+/**
+ * Compute the PREVIOUS fire-time at or before `nowMs`. Used for catchup
+ * detection: when the process restarts after a gap, we ask "what was the
+ * most recent scheduled slot?" and compare to `lastRunAtMs` to decide
+ * whether to replay.
+ *
+ * Only meaningful for `cron` + `every` kinds. `at` jobs are one-shot — if
+ * they fired, `lastRunAtMs` is set; if not, the catchup logic will simply
+ * fire them on the next tick.
+ */
+export function computePreviousRunAtMs(schedule, nowMs) {
+    switch (schedule.kind) {
+        case "at": {
+            return schedule.at <= nowMs ? schedule.at : undefined;
+        }
+        case "every": {
+            const step = Math.max(1, Math.floor(schedule.everyMs));
+            const anchor = schedule.anchorMs ?? nowMs;
+            if (nowMs < anchor)
+                return undefined;
+            const elapsed = nowMs - anchor;
+            const steps = Math.floor(elapsed / step);
+            return anchor + steps * step;
+        }
+        case "cron": {
+            const tz = resolveCronTimezone(schedule.tz);
+            const cron = getOrParseCron(schedule.expr, tz);
+            // croner's `previousRun()` takes no args (uses "now"); to anchor
+            // at our virtual `nowMs` (test-clock friendly) we use the bulk
+            // form `previousRuns(1, reference)` and grab the first result.
+            const prev = cron.previousRuns(1, new Date(nowMs));
+            const first = prev[0];
+            return first ? first.getTime() : undefined;
+        }
+    }
+}
+/** Test-only hook: clear the LRU between cases. */
+export function clearScheduleCacheForTests() {
+    parseCache.clear();
+}
+//# sourceMappingURL=schedule.js.map