@karmaniverous/jeeves-runner 0.1.0

package/dist/db/migrations/001-initial.sql

@@ -0,0 +1,61 @@
+CREATE TABLE IF NOT EXISTS jobs (
+    id              TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    schedule        TEXT NOT NULL,
+    script          TEXT NOT NULL,
+    type            TEXT DEFAULT 'script',
+    description     TEXT,
+    enabled         INTEGER DEFAULT 1,
+    timeout_ms      INTEGER,
+    overlap_policy  TEXT DEFAULT 'skip',
+    on_failure      TEXT,
+    on_success      TEXT,
+    created_at      TEXT DEFAULT (datetime('now')),
+    updated_at      TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS runs (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    job_id          TEXT NOT NULL REFERENCES jobs(id),
+    status          TEXT NOT NULL,
+    started_at      TEXT,
+    finished_at     TEXT,
+    duration_ms     INTEGER,
+    exit_code       INTEGER,
+    tokens          INTEGER,
+    result_meta     TEXT,
+    error           TEXT,
+    stdout_tail     TEXT,
+    stderr_tail     TEXT,
+    trigger         TEXT DEFAULT 'schedule'
+);
+
+CREATE INDEX IF NOT EXISTS idx_runs_job_started ON runs(job_id, started_at DESC);
+CREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);
+
+CREATE TABLE IF NOT EXISTS cursors (
+    namespace       TEXT NOT NULL,
+    key             TEXT NOT NULL,
+    value           TEXT,
+    expires_at      TEXT,
+    updated_at      TEXT DEFAULT (datetime('now')),
+    PRIMARY KEY (namespace, key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_cursors_expires ON cursors(expires_at) WHERE expires_at IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS queues (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    queue           TEXT NOT NULL,
+    payload         TEXT NOT NULL,
+    status          TEXT DEFAULT 'pending',
+    priority        INTEGER DEFAULT 0,
+    attempts        INTEGER DEFAULT 0,
+    max_attempts    INTEGER DEFAULT 1,
+    error           TEXT,
+    created_at      TEXT DEFAULT (datetime('now')),
+    claimed_at      TEXT,
+    finished_at     TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_queues_poll ON queues(queue, status, priority DESC, created_at);

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import { z } from 'zod';
+import { DatabaseSync } from 'node:sqlite';
+import { Logger } from 'pino';
+
+/**
+ * Runner configuration schema and types.
+ *
+ * @module
+ */
+
+/** Full runner configuration schema. Validates and provides defaults. */
+declare const runnerConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodNumber>;
+    dbPath: z.ZodDefault<z.ZodString>;
+    maxConcurrency: z.ZodDefault<z.ZodNumber>;
+    runRetentionDays: z.ZodDefault<z.ZodNumber>;
+    cursorCleanupIntervalMs: z.ZodDefault<z.ZodNumber>;
+    shutdownGraceMs: z.ZodDefault<z.ZodNumber>;
+    notifications: z.ZodDefault<z.ZodObject<{
+        slackTokenPath: z.ZodOptional<z.ZodString>;
+        defaultOnFailure: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        defaultOnSuccess: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    log: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            error: "error";
+            fatal: "fatal";
+        }>>;
+        file: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Inferred runner configuration type. */
+type RunnerConfig = z.infer<typeof runnerConfigSchema>;
+
+/**
+ * Job definition schema and types.
+ *
+ * @module
+ */
+
+declare const jobSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    schedule: z.ZodString;
+    script: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        script: "script";
+        session: "session";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    overlapPolicy: z.ZodDefault<z.ZodEnum<{
+        skip: "skip";
+        queue: "queue";
+        allow: "allow";
+    }>>;
+    onFailure: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    onSuccess: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type Job = z.infer<typeof jobSchema>;
+
+/**
+ * Run record schema and types.
+ *
+ * @module
+ */
+
+declare const runStatusSchema: z.ZodEnum<{
+    error: "error";
+    pending: "pending";
+    running: "running";
+    ok: "ok";
+    timeout: "timeout";
+    skipped: "skipped";
+}>;
+declare const runTriggerSchema: z.ZodEnum<{
+    schedule: "schedule";
+    manual: "manual";
+    retry: "retry";
+}>;
+declare const runSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    jobId: z.ZodString;
+    status: z.ZodEnum<{
+        error: "error";
+        pending: "pending";
+        running: "running";
+        ok: "ok";
+        timeout: "timeout";
+        skipped: "skipped";
+    }>;
+    startedAt: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    tokens: z.ZodOptional<z.ZodNumber>;
+    resultMeta: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    stdoutTail: z.ZodOptional<z.ZodString>;
+    stderrTail: z.ZodOptional<z.ZodString>;
+    trigger: z.ZodDefault<z.ZodEnum<{
+        schedule: "schedule";
+        manual: "manual";
+        retry: "retry";
+    }>>;
+}, z.core.$strip>;
+type Run = z.infer<typeof runSchema>;
+type RunStatus = z.infer<typeof runStatusSchema>;
+type RunTrigger = z.infer<typeof runTriggerSchema>;
+
+/**
+ * Main runner orchestrator. Wires up database, scheduler, API server, and handles graceful shutdown on SIGTERM/SIGINT.
+ */
+
+/** Runner interface. */
+interface Runner {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
+ */
+declare function createRunner(config: RunnerConfig): Runner;
+
+/**
+ * Job client library for runner jobs. Provides cursor (state) and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ */
+/** Client interface for job scripts to interact with runner state and queues. */
+interface RunnerClient {
+    getCursor(namespace: string, key: string): string | null;
+    setCursor(namespace: string, key: string, value: string, options?: {
+        ttl?: string;
+    }): void;
+    deleteCursor(namespace: string, key: string): void;
+    enqueue(queue: string, payload: unknown, options?: {
+        priority?: number;
+        maxAttempts?: number;
+    }): number;
+    dequeue(queue: string, count?: number): Array<{
+        id: number;
+        payload: unknown;
+    }>;
+    done(queueItemId: number): void;
+    fail(queueItemId: number, error?: string): void;
+    close(): void;
+}
+/**
+ * Create a runner client for job scripts. Opens its own DB connection.
+ */
+declare function createClient(dbPath?: string): RunnerClient;
+
+/**
+ * Job executor. Spawns job scripts as child processes, captures output, parses result metadata, enforces timeouts.
+ */
+/** Result of a job execution. */
+interface ExecutionResult {
+    status: 'ok' | 'error' | 'timeout';
+    exitCode: number | null;
+    durationMs: number;
+    tokens: number | null;
+    resultMeta: string | null;
+    stdoutTail: string;
+    stderrTail: string;
+    error: string | null;
+}
+/** Options for executing a job script. */
+interface ExecutionOptions {
+    script: string;
+    dbPath: string;
+    jobId: string;
+    runId: number;
+    timeoutMs?: number;
+}
+/**
+ * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
+ */
+declare function executeJob(options: ExecutionOptions): Promise<ExecutionResult>;
+
+/**
+ * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ */
+/** Notification configuration. */
+interface NotifyConfig {
+    slackToken: string | null;
+}
+/** Notifier interface for job completion events. */
+interface Notifier {
+    notifySuccess(jobName: string, durationMs: number, channel: string): Promise<void>;
+    notifyFailure(jobName: string, durationMs: number, error: string | null, channel: string): Promise<void>;
+}
+/**
+ * Create a notifier that sends Slack messages for job events. If no token, logs warning and returns silently.
+ */
+declare function createNotifier(config: NotifyConfig): Notifier;
+
+/**
+ * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
+ */
+
+/** Scheduler dependencies. */
+interface SchedulerDeps {
+    db: DatabaseSync;
+    executor: typeof executeJob;
+    notifier: Notifier;
+    config: RunnerConfig;
+    logger: Logger;
+}
+/** Scheduler interface. */
+interface Scheduler {
+    start(): void;
+    stop(): void;
+    triggerJob(jobId: string): Promise<ExecutionResult>;
+    getRunningJobs(): string[];
+}
+/**
+ * Create the job scheduler. Manages cron schedules, job execution, overlap policies, and notifications.
+ */
+declare function createScheduler(deps: SchedulerDeps): Scheduler;
+
+/**
+ * SQLite connection manager. Creates DB file with parent directories, enables WAL mode for concurrency.
+ */
+
+/**
+ * Create and configure a SQLite database connection.
+ * Ensures parent directories exist and enables WAL mode for better concurrency.
+ */
+declare function createConnection(dbPath: string): DatabaseSync;
+/**
+ * Close a database connection cleanly.
+ */
+declare function closeConnection(db: DatabaseSync): void;
+
+/**
+ * Database maintenance tasks: run retention pruning and expired cursor cleanup.
+ */
+
+/** Configuration for maintenance tasks. */
+interface MaintenanceConfig {
+    runRetentionDays: number;
+    cursorCleanupIntervalMs: number;
+}
+/** Maintenance controller with start/stop lifecycle. */
+interface Maintenance {
+    start(): void;
+    stop(): void;
+    /** Run all maintenance tasks immediately (useful for testing and startup). */
+    runNow(): void;
+}
+/**
+ * Create the maintenance controller. Runs cleanup tasks on startup and at configured intervals.
+ */
+declare function createMaintenance(db: DatabaseSync, config: MaintenanceConfig, logger: Logger): Maintenance;
+
+/**
+ * Schema migration runner. Tracks applied migrations via schema_version table, applies pending migrations idempotently.
+ */
+
+/**
+ * Run all pending migrations. Creates schema_version table if needed, applies migrations in order.
+ */
+declare function runMigrations(db: DatabaseSync): void;
+
+export { closeConnection, createClient, createConnection, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, jobSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };
+export type { ExecutionOptions, ExecutionResult, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, Scheduler, SchedulerDeps };