adispatchd 0.0.0-stage → 0.1.0

package/dist/runs/retention.d.ts

@@ -0,0 +1,64 @@
+import { type Clock, type Logger, type Timers } from '../core/index.js';
+import type { RetentionConfig } from '../config/index.js';
+import { type Repositories, type RunRetentionCategory } from '../persistence/index.js';
+/** Result of one retention pass. */
+export interface RetentionReport {
+    startedAt: string;
+    finishedAt: string;
+    deletedRuns: Record<RunRetentionCategory, number>;
+    deletedRunIds: string[];
+    deletedBlocks: number;
+    deletedNotifications: number;
+    deletedCronFirings: number;
+    orphanDirsRemoved: number;
+    /** File/workspace deletion problems (rows are already gone). */
+    errors: Array<{
+        runId?: string;
+        path?: string;
+        message: string;
+    }>;
+}
+/** Options of {@link RetentionService}. */
+export interface RetentionServiceOptions {
+    repositories: Pick<Repositories, 'runs' | 'retention'>;
+    dataDir: string;
+    /** Live retention settings (`config.global.retention`). */
+    settings: () => RetentionConfig;
+    clock?: Clock;
+    timers?: Timers;
+    logger?: Logger;
+    /** Runs per query batch (default 200). */
+    batchSize?: number;
+    /** Min. age of orphaned run directories before they are removed (default 24 h). */
+    orphanMinAgeMs?: number;
+    /** Called after each pass (diagnostics/SSE). */
+    onReport?: (report: RetentionReport) => void;
+}
+/** See module docs. */
+export declare class RetentionService {
+    private readonly options;
+    private readonly clock;
+    private readonly timers;
+    private readonly logger;
+    private readonly batchSize;
+    private timer;
+    private running;
+    private stopped;
+    private last;
+    constructor(options: RetentionServiceOptions);
+    /** Report of the last pass, if any. */
+    get lastReport(): RetentionReport | null;
+    /** Schedule periodic passes: first after `initialDelayMs` (default 60 s), then every `cleanup_interval`. */
+    start(initialDelayMs?: number): void;
+    /** Stop the timer and wait for a running pass. */
+    stop(): Promise<void>;
+    private arm;
+    /** Run one pass now (a call during a running pass returns that pass). */
+    runOnce(): Promise<RetentionReport>;
+    private pass;
+    private deleteRuns;
+    private removeRunFiles;
+    private removeDir;
+    /** Remove `runs/<id>` / `logs/<id>` directories whose run row no longer exists (e.g. after a failed delete). */
+    private removeOrphans;
+}

package/dist/runs/retention.js

@@ -0,0 +1,232 @@
+/**
+ * Periodic retention (Spec §5.1, §21): deletes old runs (DB rows incl.
+ * events/actions, `runs/<id>/`, `logs/<id>/`, the workspace below
+ * `workspace.base_dir`), cleared blocks, finished notifications and old cron
+ * firings according to `retention.*`.
+ *
+ * Protection rules are enforced by the persistence layer and re-checked in
+ * the deleting transaction: active runs / lock holders, unfinished or failed
+ * lifecycle chains and runs of an active retry block are never deleted.
+ * Files are deleted only after their row was deleted; the instance lock files
+ * (`adispatchd.lock*`) are never touched – only the `runs/`, `logs/`
+ * sub-directories and workspaces strictly below the base directory are.
+ */
+import { readdir, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { dataPaths, errorMessage, isValidRunId, noopLogger, resolveStrictlyWithin, systemClock, systemTimers, } from '../core/index.js';
+import { INSTANCE_LOCK_FILES } from '../persistence/index.js';
+import { removeWorkspace } from './workspace.js';
+/** Fallback age of cron firings when `completed_runs` is `never`. */
+const CRON_FIRINGS_FALLBACK_MS = 30 * 24 * 60 * 60_000;
+/** Directories in `runs/`/`logs/` without a DB row are removed only after this age. */
+const DEFAULT_ORPHAN_MIN_AGE_MS = 24 * 60 * 60_000;
+/** See module docs. */
+export class RetentionService {
+    options;
+    clock;
+    timers;
+    logger;
+    batchSize;
+    timer;
+    running;
+    stopped = false;
+    last = null;
+    constructor(options) {
+        this.options = options;
+        this.clock = options.clock ?? systemClock;
+        this.timers = options.timers ?? systemTimers;
+        this.logger = (options.logger ?? noopLogger).child({ component: 'retention' });
+        this.batchSize = options.batchSize ?? 200;
+    }
+    /** Report of the last pass, if any. */
+    get lastReport() {
+        return this.last;
+    }
+    /** Schedule periodic passes: first after `initialDelayMs` (default 60 s), then every `cleanup_interval`. */
+    start(initialDelayMs = 60_000) {
+        if (this.stopped)
+            return;
+        this.arm(initialDelayMs);
+    }
+    /** Stop the timer and wait for a running pass. */
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            this.timers.clearTimeout(this.timer);
+        this.timer = undefined;
+        await this.running?.catch(() => undefined);
+    }
+    arm(delayMs) {
+        if (this.stopped)
+            return;
+        if (this.timer)
+            this.timers.clearTimeout(this.timer);
+        this.timer = this.timers.setTimeout(() => {
+            this.timer = undefined;
+            this.runOnce()
+                .catch((err) => this.logger.error('retention pass failed', { error: errorMessage(err) }))
+                .finally(() => this.arm(this.options.settings().cleanupIntervalMs));
+        }, Math.max(0, delayMs));
+    }
+    /** Run one pass now (a call during a running pass returns that pass). */
+    runOnce() {
+        this.running ??= this.pass().finally(() => {
+            this.running = undefined;
+        });
+        return this.running;
+    }
+    async pass() {
+        const settings = this.options.settings();
+        const now = this.clock.now();
+        const report = {
+            startedAt: now.toISOString(),
+            finishedAt: now.toISOString(),
+            deletedRuns: { successful: 0, failed: 0, blocked: 0 },
+            deletedRunIds: [],
+            deletedBlocks: 0,
+            deletedNotifications: 0,
+            deletedCronFirings: 0,
+            orphanDirsRemoved: 0,
+            errors: [],
+        };
+        const cutoff = (ms) => (ms === null ? null : new Date(now.getTime() - ms));
+        const categories = [
+            ['successful', cutoff(settings.completedRunsMs)],
+            ['failed', cutoff(settings.failedRunsMs)],
+            ['blocked', cutoff(settings.blockedRunsMs)],
+        ];
+        for (const [category, before] of categories) {
+            if (before === null || this.stopped)
+                continue;
+            await this.deleteRuns(category, before, report);
+        }
+        const { retention } = this.options.repositories;
+        const blocksBefore = cutoff(settings.blockedRunsMs);
+        if (blocksBefore)
+            report.deletedBlocks = retention.deleteClearedBlocks(blocksBefore);
+        const notificationsBefore = cutoff(settings.failedRunsMs);
+        if (notificationsBefore)
+            report.deletedNotifications = retention.deleteNotifications(notificationsBefore);
+        const firingsBefore = cutoff(settings.completedRunsMs ?? CRON_FIRINGS_FALLBACK_MS);
+        if (firingsBefore)
+            report.deletedCronFirings = retention.deleteCronFirings(firingsBefore);
+        if (!this.stopped)
+            await this.removeOrphans(report);
+        report.finishedAt = this.clock.now().toISOString();
+        this.last = report;
+        const total = report.deletedRuns.successful + report.deletedRuns.failed + report.deletedRuns.blocked;
+        this.logger.info('retention pass finished', {
+            deletedRuns: report.deletedRuns,
+            deletedBlocks: report.deletedBlocks,
+            deletedNotifications: report.deletedNotifications,
+            deletedCronFirings: report.deletedCronFirings,
+            orphanDirsRemoved: report.orphanDirsRemoved,
+            errors: report.errors.length,
+            total,
+        });
+        try {
+            this.options.onReport?.(report);
+        }
+        catch (err) {
+            this.logger.warn('retention report listener failed', { error: errorMessage(err) });
+        }
+        return report;
+    }
+    async deleteRuns(category, before, report) {
+        const { runs, retention } = this.options.repositories;
+        const seen = new Set();
+        for (;;) {
+            if (this.stopped)
+                return;
+            const batch = retention.runCandidates(category, before, this.batchSize).filter((c) => !seen.has(c.runId));
+            if (batch.length === 0)
+                return;
+            for (const candidate of batch) {
+                seen.add(candidate.runId);
+                const run = runs.get(candidate.runId);
+                const baseDir = snapshotBaseDir(run?.configSnapshot);
+                // Re-checks the protection rules in the deleting transaction.
+                if (!retention.deleteRun(candidate.runId))
+                    continue;
+                report.deletedRuns[category]++;
+                report.deletedRunIds.push(candidate.runId);
+                await this.removeRunFiles(candidate.runId, candidate.workspacePath, baseDir, report);
+            }
+            // Yield between batches so HTTP/SSE stay responsive.
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+    async removeRunFiles(runId, workspacePath, baseDir, report) {
+        let paths;
+        try {
+            paths = dataPaths(this.options.dataDir).run(runId);
+        }
+        catch (err) {
+            report.errors.push({ runId, message: errorMessage(err) });
+            return;
+        }
+        for (const dir of [paths.runDir, paths.logDir])
+            await this.removeDir(dir, report, runId);
+        if (workspacePath && baseDir) {
+            const removal = await removeWorkspace(baseDir, workspacePath);
+            if (!removal.removed && removal.reason === 'error') {
+                report.errors.push({ runId, path: removal.path, message: removal.message ?? 'workspace removal failed' });
+            }
+            else if (!removal.removed && removal.reason !== 'missing') {
+                this.logger.debug('workspace not removed by retention', { runId, reason: removal.reason });
+            }
+        }
+    }
+    async removeDir(dir, report, runId) {
+        if (INSTANCE_LOCK_FILES.includes(path.basename(dir)))
+            return false;
+        try {
+            await rm(dir, { recursive: true, force: true });
+            return true;
+        }
+        catch (err) {
+            report.errors.push({ ...(runId ? { runId } : {}), path: dir, message: errorMessage(err) });
+            return false;
+        }
+    }
+    /** Remove `runs/<id>` / `logs/<id>` directories whose run row no longer exists (e.g. after a failed delete). */
+    async removeOrphans(report) {
+        const paths = dataPaths(this.options.dataDir);
+        const minAge = this.options.orphanMinAgeMs ?? DEFAULT_ORPHAN_MIN_AGE_MS;
+        const now = this.clock.now().getTime();
+        for (const parent of [paths.runsDir, paths.logsDir]) {
+            let names;
+            try {
+                names = await readdir(parent);
+            }
+            catch {
+                continue;
+            }
+            for (const name of names) {
+                if (!isValidRunId(name) || this.options.repositories.runs.get(name))
+                    continue;
+                let dir;
+                try {
+                    dir = resolveStrictlyWithin(parent, name);
+                    const st = await stat(dir);
+                    if (!st.isDirectory() || now - st.mtimeMs < minAge)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                // Re-check right before deleting (a run could have been created meanwhile – IDs are unique, so only a stale dir matches).
+                if (this.options.repositories.runs.get(name))
+                    continue;
+                if (await this.removeDir(dir, report))
+                    report.orphanDirsRemoved++;
+            }
+        }
+    }
+}
+/** `workspace.baseDir` from a run's config snapshot, if present. */
+function snapshotBaseDir(snapshot) {
+    const ws = snapshot?.workspace;
+    return typeof ws?.baseDir === 'string' ? ws.baseDir : null;
+}
+//# sourceMappingURL=retention.js.map

package/dist/runs/retention.js.map

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

package/dist/runs/workspace.d.ts

@@ -0,0 +1,20 @@
+import { type BusinessResult, type TerminalStatus } from '../core/index.js';
+import type { WorkspaceCleanup } from '../config/index.js';
+/** True if the policy asks to delete the workspace of a run with this outcome. */
+export declare function shouldCleanupWorkspace(policy: WorkspaceCleanup, status: TerminalStatus, businessResult: BusinessResult): boolean;
+/** Outcome of {@link removeWorkspace}. */
+export type WorkspaceRemoval = {
+    removed: true;
+    path: string;
+} | {
+    removed: false;
+    path: string;
+    reason: 'missing' | 'outside_base_dir' | 'symlink' | 'error';
+    message?: string;
+};
+/**
+ * Delete the run workspace `workspacePath` if – lexically AND after resolving
+ * symlinks of its parents – it lies strictly below `baseDir`. A workspace
+ * that is itself a symlink is never followed or deleted. Never throws.
+ */
+export declare function removeWorkspace(baseDir: string, workspacePath: string): Promise<WorkspaceRemoval>;

package/dist/runs/workspace.js

@@ -0,0 +1,51 @@
+/**
+ * Workspace cleanup after a run (Spec §5.1 `workspace.cleanup`, §9, §20):
+ * only directories strictly below `workspace.base_dir` are ever deleted.
+ */
+import { lstat, realpath, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { isWithin, resolveStrictlyWithin } from '../core/index.js';
+/** True if the policy asks to delete the workspace of a run with this outcome. */
+export function shouldCleanupWorkspace(policy, status, businessResult) {
+    switch (policy) {
+        case 'always':
+            return true;
+        case 'never':
+            return false;
+        case 'on_success':
+            return status === 'completed' && businessResult === 'success';
+    }
+}
+/**
+ * Delete the run workspace `workspacePath` if – lexically AND after resolving
+ * symlinks of its parents – it lies strictly below `baseDir`. A workspace
+ * that is itself a symlink is never followed or deleted. Never throws.
+ */
+export async function removeWorkspace(baseDir, workspacePath) {
+    let target;
+    try {
+        target = resolveStrictlyWithin(baseDir, workspacePath);
+    }
+    catch (err) {
+        return { removed: false, path: workspacePath, reason: 'outside_base_dir', message: err.message };
+    }
+    try {
+        const st = await lstat(target);
+        if (st.isSymbolicLink())
+            return { removed: false, path: target, reason: 'symlink' };
+        const [realBase, realTarget] = await Promise.all([realpath(baseDir), realpath(target)]);
+        if (!isWithin(realBase, realTarget) || path.resolve(realBase) === path.resolve(realTarget)) {
+            return { removed: false, path: target, reason: 'outside_base_dir', message: `resolves to ${realTarget}` };
+        }
+        // `rm` does not follow symlinks inside the tree; it removes the links themselves.
+        await rm(realTarget, { recursive: true, force: true });
+        return { removed: true, path: target };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { removed: false, path: target, reason: 'missing' };
+        return { removed: false, path: target, reason: 'error', message: err.message };
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/runs/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/runs/workspace.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAA4C,MAAM,kBAAkB,CAAC;AAG7G,kFAAkF;AAClF,MAAM,UAAU,sBAAsB,CAAC,MAAwB,EAAE,MAAsB,EAAE,cAA8B;IACrH,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC;QACd,KAAK,OAAO;YACV,OAAO,KAAK,CAAC;QACf,KAAK,YAAY;YACf,OAAO,MAAM,KAAK,WAAW,IAAI,cAAc,KAAK,SAAS,CAAC;IAClE,CAAC;AACH,CAAC;AAOD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAe,EAAE,aAAqB;IAC1E,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,qBAAqB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC;IAC9G,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,EAAE,CAAC,cAAc,EAAE;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QACpF,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACxF,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3F,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE,OAAO,EAAE,eAAe,UAAU,EAAE,EAAE,CAAC;QAC5G,CAAC;QACD,kFAAkF;QAClF,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;QAClF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC;IAC5F,CAAC;AACH,CAAC"}

package/dist/scheduler/checks.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shell filter and conditions for the scheduler (Spec §6, §7 step 5):
+ * argument templates, check context, workflow-condition cache, diagnoses.
+ */
+import { type SourceItem, type TriValue } from '../core/index.js';
+import type { ShellFilterConfig, WorkflowConfig } from '../config/index.js';
+import { type ShellCheckRunner } from '../filters/index.js';
+import type { CheckDiagnosis, CheckKind } from './types.js';
+/** Combined result of a list of checks (all must be `true`). */
+export interface ChecksOutcome {
+    value: TriValue;
+    checks: CheckDiagnosis[];
+    /** First check that was not `true`. */
+    failed: CheckDiagnosis | null;
+}
+/** Diagnosis entry for a check that was not executed. */
+export declare function notEvaluatedCheck(kind: CheckKind, index: number, command: string): CheckDiagnosis;
+/** Diagnoses for all workflow conditions, none executed. */
+export declare function notEvaluatedConditions(workflow: WorkflowConfig, kind: 'workflow_condition' | 'item_condition'): CheckDiagnosis[];
+/** Item context for item-bound checks. */
+export interface CheckItem {
+    item: SourceItem;
+    sourceType: string;
+    repository?: string;
+}
+/** Runs the scheduler's shell checks. */
+export declare class SchedulerChecks {
+    private readonly runner;
+    private readonly now;
+    constructor(runner: ShellCheckRunner, now: () => Date);
+    /** Cache key of a workflow condition (WI-04 proposal). */
+    static conditionCacheKey(workflowId: string, index: number): string;
+    /** Workflow conditions in order; stops at the first non-`true` (rest `not_evaluated`). Cached per `cache` TTL. */
+    workflowConditions(workflow: WorkflowConfig, signal?: AbortSignal): Promise<ChecksOutcome>;
+    /** Item conditions in order (never cached). */
+    itemConditions(workflow: WorkflowConfig, target: CheckItem, signal?: AbortSignal): Promise<ChecksOutcome>;
+    /** Shell filter of a workflow for one item (never cached). */
+    shellFilter(workflow: WorkflowConfig, filter: ShellFilterConfig, target: CheckItem, signal?: AbortSignal): Promise<CheckDiagnosis>;
+    private runList;
+    private runOne;
+}

package/dist/scheduler/checks.js

@@ -0,0 +1,111 @@
+/**
+ * Shell filter and conditions for the scheduler (Spec §6, §7 step 5):
+ * argument templates, check context, workflow-condition cache, diagnoses.
+ */
+import { buildTemplateValues, errorMessage, renderTemplate } from '../core/index.js';
+import { buildCheckContext } from '../filters/index.js';
+/** Diagnosis entry for a check that was not executed. */
+export function notEvaluatedCheck(kind, index, command) {
+    return { kind, index, command, value: 'not_evaluated', cached: false, exitCode: null, error: null, durationMs: null };
+}
+/** Diagnoses for all workflow conditions, none executed. */
+export function notEvaluatedConditions(workflow, kind) {
+    const list = kind === 'workflow_condition' ? workflow.conditions.workflow : workflow.conditions.item;
+    return list.map((c, i) => notEvaluatedCheck(kind, i, c.command));
+}
+function fromResult(kind, index, command, r) {
+    return {
+        kind,
+        index,
+        command,
+        value: r.value,
+        cached: r.cached,
+        exitCode: r.exitCode,
+        error: r.value === 'unknown' ? (r.error ?? 'check error') : null,
+        durationMs: r.durationMs,
+    };
+}
+function templateValues(workflow, now, item, sourceType, repository) {
+    const title = item?.fields.title;
+    return buildTemplateValues({
+        workflow: { id: workflow.id, name: workflow.name },
+        ...(item
+            ? {
+                source: { id: item.sourceId, type: sourceType ?? '', ...(repository !== undefined ? { repository } : {}) },
+                item: {
+                    id: item.itemId,
+                    key: item.key,
+                    ...(/^\d+$/.test(item.itemId) ? { number: item.itemId } : {}),
+                    url: item.url,
+                    ...(typeof title === 'string' ? { title } : {}),
+                },
+            }
+            : {}),
+        now,
+    });
+}
+/** Runs the scheduler's shell checks. */
+export class SchedulerChecks {
+    runner;
+    now;
+    constructor(runner, now) {
+        this.runner = runner;
+        this.now = now;
+    }
+    /** Cache key of a workflow condition (WI-04 proposal). */
+    static conditionCacheKey(workflowId, index) {
+        return `${workflowId}:condition:${index}`;
+    }
+    /** Workflow conditions in order; stops at the first non-`true` (rest `not_evaluated`). Cached per `cache` TTL. */
+    async workflowConditions(workflow, signal) {
+        return this.runList(workflow, 'workflow_condition', workflow.conditions.workflow, undefined, signal);
+    }
+    /** Item conditions in order (never cached). */
+    async itemConditions(workflow, target, signal) {
+        return this.runList(workflow, 'item_condition', workflow.conditions.item, target, signal);
+    }
+    /** Shell filter of a workflow for one item (never cached). */
+    async shellFilter(workflow, filter, target, signal) {
+        const spec = { command: filter.command, timeoutMs: filter.timeoutMs };
+        const ctx = buildCheckContext('shell_filter', workflow.id, target.item, target.sourceType);
+        const result = await this.runner.run(spec, ctx, signal ? { signal } : {});
+        return fromResult('shell_filter', 0, filter.command, result);
+    }
+    async runList(workflow, kind, list, target, signal) {
+        const checks = [];
+        let failed = null;
+        for (const [index, condition] of list.entries()) {
+            if (failed) {
+                checks.push(notEvaluatedCheck(kind, index, condition.command));
+                continue;
+            }
+            const diag = await this.runOne(workflow, kind, index, condition, target, signal);
+            checks.push(diag);
+            if (diag.value !== true)
+                failed = diag;
+        }
+        const value = failed === null ? true : failed.value === false ? false : 'unknown';
+        return { value, checks, failed };
+    }
+    async runOne(workflow, kind, index, condition, target, signal) {
+        let args;
+        try {
+            const values = templateValues(workflow, this.now(), target?.item, target?.sourceType, target?.repository);
+            const scope = kind === 'item_condition' ? { source: true } : {};
+            args = condition.args.map((a) => renderTemplate(a, values, { mode: 'text', scope }));
+        }
+        catch (err) {
+            return { ...notEvaluatedCheck(kind, index, condition.command), value: 'unknown', error: `argument template: ${errorMessage(err)}` };
+        }
+        const spec = { command: condition.command, args, timeoutMs: condition.timeoutMs };
+        const ctx = kind === 'item_condition' && target
+            ? buildCheckContext('item_condition', workflow.id, target.item, target.sourceType)
+            : buildCheckContext('workflow_condition', workflow.id);
+        const opts = signal ? { signal } : {};
+        const result = kind === 'workflow_condition' && condition.cacheMs !== null && condition.cacheMs > 0
+            ? await this.runner.runCached(SchedulerChecks.conditionCacheKey(workflow.id, index), condition.cacheMs, spec, ctx, opts)
+            : await this.runner.run(spec, ctx, opts);
+        return fromResult(kind, index, condition.command, result);
+    }
+}
+//# sourceMappingURL=checks.js.map

package/dist/scheduler/checks.js.map

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

package/dist/scheduler/cron.d.ts

@@ -0,0 +1,32 @@
+/** A parsed cron schedule (paused croner instance – it never fires on its own). */
+export interface CronSchedule {
+    readonly expression: string;
+    readonly timezone: string;
+    /** First slot strictly after `after`, or `null` if the expression never fires again. */
+    next(after: Date): Date | null;
+}
+/**
+ * Parse a cron expression for a time zone (croner syntax, 5 or 6 fields).
+ * @throws Error for invalid expressions/time zones (config validation rejects them earlier).
+ */
+export declare function parseCron(expression: string, timezone: string): CronSchedule;
+/** The next `count` slots strictly after `after`. */
+export declare function nextSlots(schedule: CronSchedule, after: Date, count: number): Date[];
+/** Result of {@link dueSlots}. */
+export interface DueSlots {
+    /** The most recent due slots (ascending), at most `keep`. */
+    slots: Date[];
+    /** Total number of due slots found (≥ `slots.length`). */
+    total: number;
+    /** True if scanning stopped at `maxScan` before reaching `now` (older slots were not counted). */
+    scanLimited: boolean;
+}
+/**
+ * All slots in `(after, now]`, keeping only the most recent `keep` of them.
+ * Scanning is bounded by `maxScan`; if hit, scanning restarts closer to
+ * `now` so that the most recent slots are still found.
+ */
+export declare function dueSlots(schedule: CronSchedule, after: Date, now: Date, options: {
+    keep: number;
+    maxScan: number;
+}): DueSlots;