@karmaniverous/jeeves-runner 0.1.0

package/dist/cli/jeeves-runner/index.js

@@ -0,0 +1,880 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { Command } from 'commander';
+import { DatabaseSync } from 'node:sqlite';
+import { pino } from 'pino';
+import Fastify from 'fastify';
+import { request } from 'node:https';
+import { spawn } from 'node:child_process';
+import { Cron } from 'croner';
+import { z } from 'zod';
+
+/**
+ * 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.
+ */
+function createConnection(dbPath) {
+    // Ensure parent directory exists
+    const dir = dirname(dbPath);
+    mkdirSync(dir, { recursive: true });
+    // Open database
+    const db = new DatabaseSync(dbPath);
+    // Enable WAL mode for better concurrency
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    return db;
+}
+/**
+ * Close a database connection cleanly.
+ */
+function closeConnection(db) {
+    db.close();
+}
+
+/**
+ * Schema migration runner. Tracks applied migrations via schema_version table, applies pending migrations idempotently.
+ */
+/** Initial schema migration SQL (embedded to avoid runtime file resolution issues). */
+const MIGRATION_001 = `
+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);
+`;
+/** Registry of all migrations keyed by version number. */
+const MIGRATIONS = {
+    1: MIGRATION_001,
+};
+/**
+ * Run all pending migrations. Creates schema_version table if needed, applies migrations in order.
+ */
+function runMigrations(db) {
+    // Create schema_version table if it doesn't exist
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_version (
+      version INTEGER PRIMARY KEY,
+      applied_at TEXT DEFAULT (datetime('now'))
+    );
+  `);
+    // Get current version
+    const currentVersionRow = db
+        .prepare('SELECT MAX(version) as version FROM schema_version')
+        .get();
+    const currentVersion = currentVersionRow?.version ?? 0;
+    // Apply pending migrations
+    const pendingVersions = Object.keys(MIGRATIONS)
+        .map(Number)
+        .filter((v) => v > currentVersion)
+        .sort((a, b) => a - b);
+    for (const version of pendingVersions) {
+        db.exec(MIGRATIONS[version]);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(version);
+    }
+}
+
+/**
+ * Fastify API routes for job management and monitoring. Provides endpoints for job CRUD, run history, manual triggers, and system stats.
+ */
+/**
+ * Register all API routes on the Fastify instance.
+ */
+function registerRoutes(app, deps) {
+    const { db, scheduler } = deps;
+    /** GET /health — Health check. */
+    app.get('/health', () => {
+        return { ok: true, uptime: process.uptime() };
+    });
+    /** GET /jobs — List all jobs with last run status. */
+    app.get('/jobs', () => {
+        const rows = db
+            .prepare(`SELECT j.*, 
+          (SELECT status FROM runs WHERE job_id = j.id ORDER BY started_at DESC LIMIT 1) as last_status,
+          (SELECT started_at FROM runs WHERE job_id = j.id ORDER BY started_at DESC LIMIT 1) as last_run
+         FROM jobs j`)
+            .all();
+        return { jobs: rows };
+    });
+    /** GET /jobs/:id — Single job detail. */
+    app.get('/jobs/:id', async (request, reply) => {
+        const job = db
+            .prepare('SELECT * FROM jobs WHERE id = ?')
+            .get(request.params.id);
+        if (!job) {
+            reply.code(404);
+            return { error: 'Job not found' };
+        }
+        return { job };
+    });
+    /** GET /jobs/:id/runs — Run history for a job. */
+    app.get('/jobs/:id/runs', (request) => {
+        const limit = parseInt(request.query.limit ?? '50', 10);
+        const runs = db
+            .prepare('SELECT * FROM runs WHERE job_id = ? ORDER BY started_at DESC LIMIT ?')
+            .all(request.params.id, limit);
+        return { runs };
+    });
+    /** POST /jobs/:id/run — Trigger manual job run. */
+    app.post('/jobs/:id/run', async (request, reply) => {
+        try {
+            const result = await scheduler.triggerJob(request.params.id);
+            return { result };
+        }
+        catch (err) {
+            reply.code(404);
+            return { error: err instanceof Error ? err.message : 'Unknown error' };
+        }
+    });
+    /** POST /jobs/:id/enable — Enable a job. */
+    app.post('/jobs/:id/enable', (request, reply) => {
+        const result = db
+            .prepare('UPDATE jobs SET enabled = 1 WHERE id = ?')
+            .run(request.params.id);
+        if (result.changes === 0) {
+            reply.code(404);
+            return { error: 'Job not found' };
+        }
+        return { ok: true };
+    });
+    /** POST /jobs/:id/disable — Disable a job. */
+    app.post('/jobs/:id/disable', (request, reply) => {
+        const result = db
+            .prepare('UPDATE jobs SET enabled = 0 WHERE id = ?')
+            .run(request.params.id);
+        if (result.changes === 0) {
+            reply.code(404);
+            return { error: 'Job not found' };
+        }
+        return { ok: true };
+    });
+    /** GET /stats — Aggregate job statistics. */
+    app.get('/stats', () => {
+        const totalJobs = db
+            .prepare('SELECT COUNT(*) as count FROM jobs')
+            .get();
+        const runningCount = scheduler.getRunningJobs().length;
+        const okLastHour = db
+            .prepare(`SELECT COUNT(*) as count FROM runs 
+         WHERE status = 'ok' AND started_at > datetime('now', '-1 hour')`)
+            .get();
+        const errorsLastHour = db
+            .prepare(`SELECT COUNT(*) as count FROM runs 
+         WHERE status IN ('error', 'timeout') AND started_at > datetime('now', '-1 hour')`)
+            .get();
+        return {
+            totalJobs: totalJobs.count,
+            running: runningCount,
+            okLastHour: okLastHour.count,
+            errorsLastHour: errorsLastHour.count,
+        };
+    });
+}
+
+/**
+ * Fastify HTTP server for runner API. Creates server instance with logging, registers routes, listens on configured port (localhost only).
+ */
+/**
+ * Create and configure the Fastify server. Routes are registered but server is not started.
+ */
+function createServer(config, deps) {
+    const app = Fastify({
+        logger: {
+            level: config.log.level,
+            ...(config.log.file
+                ? {
+                    transport: {
+                        target: 'pino/file',
+                        options: { destination: config.log.file },
+                    },
+                }
+                : {}),
+        },
+    });
+    registerRoutes(app, deps);
+    return app;
+}
+
+/**
+ * Database maintenance tasks: run retention pruning and expired cursor cleanup.
+ */
+/** Delete runs older than the configured retention period. */
+function pruneOldRuns(db, days, logger) {
+    const result = db
+        .prepare(`DELETE FROM runs WHERE started_at < datetime('now', '-${String(days)} days')`)
+        .run();
+    if (result.changes > 0) {
+        logger.info({ deleted: result.changes }, 'Pruned old runs');
+    }
+}
+/** Delete expired cursor entries. */
+function cleanExpiredCursors(db, logger) {
+    const result = db
+        .prepare(`DELETE FROM cursors WHERE expires_at IS NOT NULL AND expires_at < datetime('now')`)
+        .run();
+    if (result.changes > 0) {
+        logger.info({ deleted: result.changes }, 'Cleaned expired cursors');
+    }
+}
+/**
+ * Create the maintenance controller. Runs cleanup tasks on startup and at configured intervals.
+ */
+function createMaintenance(db, config, logger) {
+    let interval = null;
+    function runAll() {
+        pruneOldRuns(db, config.runRetentionDays, logger);
+        cleanExpiredCursors(db, logger);
+    }
+    return {
+        start() {
+            // Run immediately on startup
+            runAll();
+            // Then run periodically
+            interval = setInterval(runAll, config.cursorCleanupIntervalMs);
+        },
+        stop() {
+            if (interval) {
+                clearInterval(interval);
+                interval = null;
+            }
+        },
+        runNow() {
+            runAll();
+        },
+    };
+}
+
+/**
+ * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ */
+/** Post a message to Slack via chat.postMessage API. */
+function postToSlack(token, channel, text) {
+    return new Promise((resolve, reject) => {
+        const payload = JSON.stringify({ channel, text });
+        const req = request('https://slack.com/api/chat.postMessage', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${token}`,
+                'Content-Length': Buffer.byteLength(payload),
+            },
+        }, (res) => {
+            let body = '';
+            res.on('data', (chunk) => {
+                body += chunk.toString();
+            });
+            res.on('end', () => {
+                if (res.statusCode === 200) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Slack API returned ${String(res.statusCode)}: ${body}`));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.write(payload);
+        req.end();
+    });
+}
+/**
+ * Create a notifier that sends Slack messages for job events. If no token, logs warning and returns silently.
+ */
+function createNotifier(config) {
+    const { slackToken } = config;
+    return {
+        async notifySuccess(jobName, durationMs, channel) {
+            if (!slackToken) {
+                console.warn(`No Slack token configured — skipping success notification for ${jobName}`);
+                return;
+            }
+            const durationSec = (durationMs / 1000).toFixed(1);
+            const text = `✅ *${jobName}* completed (${durationSec}s)`;
+            await postToSlack(slackToken, channel, text);
+        },
+        async notifyFailure(jobName, durationMs, error, channel) {
+            if (!slackToken) {
+                console.warn(`No Slack token configured — skipping failure notification for ${jobName}`);
+                return;
+            }
+            const durationSec = (durationMs / 1000).toFixed(1);
+            const errorMsg = error ? `: ${error}` : '';
+            const text = `⚠️ *${jobName}* failed (${durationSec}s)${errorMsg}`;
+            await postToSlack(slackToken, channel, text);
+        },
+    };
+}
+
+/**
+ * Job executor. Spawns job scripts as child processes, captures output, parses result metadata, enforces timeouts.
+ */
+/** Ring buffer for capturing last N lines of output. */
+class RingBuffer {
+    maxLines;
+    lines = [];
+    constructor(maxLines) {
+        this.maxLines = maxLines;
+    }
+    append(line) {
+        this.lines.push(line);
+        if (this.lines.length > this.maxLines) {
+            this.lines.shift();
+        }
+    }
+    getAll() {
+        return this.lines.join('\n');
+    }
+}
+/** Parse JR_RESULT:\{json\} lines from stdout to extract tokens and resultMeta. */
+function parseResultLines(stdout) {
+    const lines = stdout.split('\n');
+    let tokens = null;
+    let resultMeta = null;
+    for (const line of lines) {
+        const match = /^JR_RESULT:(.+)$/.exec(line.trim());
+        if (match) {
+            try {
+                const data = JSON.parse(match[1]);
+                if (data.tokens !== undefined)
+                    tokens = data.tokens;
+                if (data.meta !== undefined)
+                    resultMeta = data.meta;
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    return { tokens, resultMeta };
+}
+/**
+ * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
+ */
+function executeJob(options) {
+    const { script, dbPath, jobId, runId, timeoutMs } = options;
+    const startTime = Date.now();
+    return new Promise((resolve) => {
+        const stdoutBuffer = new RingBuffer(100);
+        const stderrBuffer = new RingBuffer(100);
+        const child = spawn('node', [script], {
+            env: {
+                ...process.env,
+                JR_DB_PATH: dbPath,
+                JR_JOB_ID: jobId,
+                JR_RUN_ID: String(runId),
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let timedOut = false;
+        let timeoutHandle = null;
+        if (timeoutMs) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+                setTimeout(() => child.kill('SIGKILL'), 5000); // Force kill after 5s
+            }, timeoutMs);
+        }
+        child.stdout.on('data', (chunk) => {
+            const lines = chunk.toString().split('\n');
+            for (const line of lines) {
+                if (line.trim())
+                    stdoutBuffer.append(line);
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            const lines = chunk.toString().split('\n');
+            for (const line of lines) {
+                if (line.trim())
+                    stderrBuffer.append(line);
+            }
+        });
+        child.on('close', (exitCode) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            const durationMs = Date.now() - startTime;
+            const stdoutTail = stdoutBuffer.getAll();
+            const stderrTail = stderrBuffer.getAll();
+            const { tokens, resultMeta } = parseResultLines(stdoutTail);
+            if (timedOut) {
+                resolve({
+                    status: 'timeout',
+                    exitCode: null,
+                    durationMs,
+                    tokens: null,
+                    resultMeta: null,
+                    stdoutTail,
+                    stderrTail,
+                    error: `Job timed out after ${String(timeoutMs)}ms`,
+                });
+            }
+            else if (exitCode === 0) {
+                resolve({
+                    status: 'ok',
+                    exitCode,
+                    durationMs,
+                    tokens,
+                    resultMeta,
+                    stdoutTail,
+                    stderrTail,
+                    error: null,
+                });
+            }
+            else {
+                resolve({
+                    status: 'error',
+                    exitCode,
+                    durationMs,
+                    tokens,
+                    resultMeta,
+                    stdoutTail,
+                    stderrTail,
+                    error: stderrTail || `Exit code ${String(exitCode)}`,
+                });
+            }
+        });
+        child.on('error', (err) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            const durationMs = Date.now() - startTime;
+            resolve({
+                status: 'error',
+                exitCode: null,
+                durationMs,
+                tokens: null,
+                resultMeta: null,
+                stdoutTail: stdoutBuffer.getAll(),
+                stderrTail: stderrBuffer.getAll(),
+                error: err.message,
+            });
+        });
+    });
+}
+
+/**
+ * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
+ */
+/**
+ * Create the job scheduler. Manages cron schedules, job execution, overlap policies, and notifications.
+ */
+function createScheduler(deps) {
+    const { db, executor, notifier, config, logger } = deps;
+    const crons = new Map();
+    const runningJobs = new Set();
+    /** Insert a run record and return its ID. */
+    function createRun(jobId, trigger) {
+        const result = db
+            .prepare(`INSERT INTO runs (job_id, status, started_at, trigger) 
+         VALUES (?, 'running', datetime('now'), ?)`)
+            .run(jobId, trigger);
+        return result.lastInsertRowid;
+    }
+    /** Update run record with completion data. */
+    function finishRun(runId, execResult) {
+        db.prepare(`UPDATE runs SET status = ?, finished_at = datetime('now'), duration_ms = ?, 
+       exit_code = ?, tokens = ?, result_meta = ?, error = ?, stdout_tail = ?, stderr_tail = ?
+       WHERE id = ?`).run(execResult.status, execResult.durationMs, execResult.exitCode, execResult.tokens, execResult.resultMeta, execResult.error, execResult.stdoutTail, execResult.stderrTail, runId);
+    }
+    /** Execute a job: create run record, run script, update record, send notifications. */
+    async function runJob(job, trigger) {
+        const { id, name, script, timeout_ms, on_success, on_failure } = job;
+        // Check concurrency limit
+        if (runningJobs.size >= config.maxConcurrency) {
+            logger.warn({ jobId: id }, 'Max concurrency reached, skipping job');
+            throw new Error('Max concurrency reached');
+        }
+        runningJobs.add(id);
+        const runId = createRun(id, trigger);
+        logger.info({ jobId: id, runId, trigger }, 'Starting job');
+        try {
+            const result = await executor({
+                script,
+                dbPath: config.dbPath,
+                jobId: id,
+                runId,
+                timeoutMs: timeout_ms ?? undefined,
+            });
+            finishRun(runId, result);
+            logger.info({ jobId: id, runId, status: result.status }, 'Job finished');
+            // Send notifications
+            if (result.status === 'ok' && on_success) {
+                await notifier
+                    .notifySuccess(name, result.durationMs, on_success)
+                    .catch((err) => {
+                    logger.error({ jobId: id, err }, 'Notification failed');
+                });
+            }
+            else if (result.status !== 'ok' && on_failure) {
+                await notifier
+                    .notifyFailure(name, result.durationMs, result.error, on_failure)
+                    .catch((err) => {
+                    logger.error({ jobId: id, err }, 'Notification failed');
+                });
+            }
+            return result;
+        }
+        finally {
+            runningJobs.delete(id);
+        }
+    }
+    /** Handle scheduled job fire. */
+    async function onScheduledRun(job) {
+        const { id, overlap_policy } = job;
+        // Check overlap policy
+        if (runningJobs.has(id)) {
+            if (overlap_policy === 'skip') {
+                logger.info({ jobId: id }, 'Job already running, skipping (overlap_policy=skip)');
+                return;
+            }
+            else if (overlap_policy === 'queue') {
+                logger.info({ jobId: id }, 'Job already running, queueing (overlap_policy=queue)');
+                // In a real implementation, we'd queue this. For now, just skip.
+                return;
+            }
+            // 'allow' policy: proceed
+        }
+        await runJob(job, 'schedule').catch((err) => {
+            logger.error({ jobId: id, err }, 'Job execution failed');
+        });
+    }
+    return {
+        start() {
+            // Load all enabled jobs
+            const jobs = db
+                .prepare('SELECT * FROM jobs WHERE enabled = 1')
+                .all();
+            logger.info({ count: jobs.length }, 'Loading jobs');
+            for (const job of jobs) {
+                try {
+                    const cron = new Cron(job.schedule, () => {
+                        void onScheduledRun(job);
+                    });
+                    crons.set(job.id, cron);
+                    logger.info({ jobId: job.id, schedule: job.schedule }, 'Scheduled job');
+                }
+                catch (err) {
+                    logger.error({ jobId: job.id, err }, 'Failed to schedule job');
+                }
+            }
+        },
+        stop() {
+            logger.info('Stopping scheduler');
+            // Stop all crons
+            for (const cron of crons.values()) {
+                cron.stop();
+            }
+            crons.clear();
+            // Wait for running jobs (simple poll with timeout)
+            const deadline = Date.now() + config.shutdownGraceMs;
+            const checkInterval = setInterval(() => {
+                if (runningJobs.size === 0 || Date.now() > deadline) {
+                    clearInterval(checkInterval);
+                    if (runningJobs.size > 0) {
+                        logger.warn({ count: runningJobs.size }, 'Forced shutdown with running jobs');
+                    }
+                }
+            }, 100);
+        },
+        async triggerJob(jobId) {
+            const job = db.prepare('SELECT * FROM jobs WHERE id = ?').get(jobId);
+            if (!job)
+                throw new Error(`Job not found: ${jobId}`);
+            return runJob(job, 'manual');
+        },
+        getRunningJobs() {
+            return Array.from(runningJobs);
+        },
+    };
+}
+
+/**
+ * Main runner orchestrator. Wires up database, scheduler, API server, and handles graceful shutdown on SIGTERM/SIGINT.
+ */
+/**
+ * Create the runner. Initializes database, scheduler, API server, and sets up graceful shutdown.
+ */
+function createRunner(config) {
+    let db = null;
+    let scheduler = null;
+    let server = null;
+    let maintenance = null;
+    const logger = pino({
+        level: config.log.level,
+        ...(config.log.file
+            ? {
+                transport: {
+                    target: 'pino/file',
+                    options: { destination: config.log.file },
+                },
+            }
+            : {}),
+    });
+    return {
+        async start() {
+            logger.info('Starting runner');
+            // Database
+            db = createConnection(config.dbPath);
+            runMigrations(db);
+            logger.info({ dbPath: config.dbPath }, 'Database ready');
+            // Notifier
+            const slackToken = config.notifications.slackTokenPath
+                ? readFileSync(config.notifications.slackTokenPath, 'utf-8').trim()
+                : null;
+            const notifier = createNotifier({ slackToken });
+            // Maintenance (run retention pruning + cursor cleanup)
+            maintenance = createMaintenance(db, {
+                runRetentionDays: config.runRetentionDays,
+                cursorCleanupIntervalMs: config.cursorCleanupIntervalMs,
+            }, logger);
+            maintenance.start();
+            logger.info('Maintenance tasks started');
+            // Scheduler
+            scheduler = createScheduler({
+                db,
+                executor: executeJob,
+                notifier,
+                config,
+                logger,
+            });
+            scheduler.start();
+            logger.info('Scheduler started');
+            // API server
+            server = createServer(config, { db, scheduler });
+            await server.listen({ port: config.port, host: '127.0.0.1' });
+            logger.info({ port: config.port }, 'API server listening');
+            // Graceful shutdown
+            const shutdown = async (signal) => {
+                logger.info({ signal }, 'Received shutdown signal');
+                await this.stop();
+                process.exit(0);
+            };
+            process.on('SIGTERM', () => {
+                void shutdown('SIGTERM');
+            });
+            process.on('SIGINT', () => {
+                void shutdown('SIGINT');
+            });
+        },
+        async stop() {
+            logger.info('Stopping runner');
+            if (maintenance) {
+                maintenance.stop();
+                logger.info('Maintenance stopped');
+            }
+            if (scheduler) {
+                scheduler.stop();
+                logger.info('Scheduler stopped');
+            }
+            if (server) {
+                await server.close();
+                logger.info('API server stopped');
+            }
+            if (db) {
+                closeConnection(db);
+                logger.info('Database closed');
+            }
+        },
+    };
+}
+
+/**
+ * Runner configuration schema and types.
+ *
+ * @module
+ */
+/** Notification configuration sub-schema. */
+const notificationsSchema = z.object({
+    slackTokenPath: z.string().optional(),
+    defaultOnFailure: z.string().nullable().default(null),
+    defaultOnSuccess: z.string().nullable().default(null),
+});
+/** Log configuration sub-schema. */
+const logSchema = z.object({
+    level: z
+        .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
+        .default('info'),
+    file: z.string().optional(),
+});
+/** Full runner configuration schema. Validates and provides defaults. */
+const runnerConfigSchema = z.object({
+    port: z.number().default(3100),
+    dbPath: z.string().default('./data/runner.sqlite'),
+    maxConcurrency: z.number().default(4),
+    runRetentionDays: z.number().default(30),
+    cursorCleanupIntervalMs: z.number().default(3600000),
+    shutdownGraceMs: z.number().default(30000),
+    notifications: notificationsSchema.default({
+        defaultOnFailure: null,
+        defaultOnSuccess: null,
+    }),
+    log: logSchema.default({ level: 'info' }),
+});
+
+/**
+ * CLI entry point for jeeves-runner.
+ *
+ * @module
+ */
+/** Load and validate config from a JSON file path, or return defaults. */
+function loadConfig(configPath) {
+    if (configPath) {
+        const raw = readFileSync(resolve(configPath), 'utf-8');
+        return runnerConfigSchema.parse(JSON.parse(raw));
+    }
+    return runnerConfigSchema.parse({});
+}
+const program = new Command();
+program
+    .name('jeeves-runner')
+    .description('Graph-aware job execution engine with SQLite state')
+    .version('0.0.0');
+program
+    .command('start')
+    .description('Start the runner daemon')
+    .option('-c, --config <path>', 'Path to config file')
+    .action((options) => {
+    const config = loadConfig(options.config);
+    const runner = createRunner(config);
+    void runner.start();
+});
+program
+    .command('status')
+    .description('Show runner status')
+    .option('-c, --config <path>', 'Path to config file')
+    .action((options) => {
+    const config = loadConfig(options.config);
+    void (async () => {
+        try {
+            const resp = await fetch(`http://127.0.0.1:${String(config.port)}/stats`);
+            const stats = (await resp.json());
+            console.log(JSON.stringify(stats, null, 2));
+        }
+        catch {
+            console.error(`Runner not reachable on port ${String(config.port)}. Is it running?`);
+            process.exit(1);
+        }
+    })();
+});
+program
+    .command('add-job')
+    .description('Add a new job')
+    .requiredOption('-i, --id <id>', 'Job ID')
+    .requiredOption('-n, --name <name>', 'Job name')
+    .requiredOption('-s, --schedule <schedule>', 'Cron schedule')
+    .requiredOption('--script <script>', 'Absolute path to script')
+    .option('-t, --type <type>', 'Job type (script|session)', 'script')
+    .option('-d, --description <desc>', 'Job description')
+    .option('--timeout <ms>', 'Timeout in ms')
+    .option('--overlap <policy>', 'Overlap policy (skip|queue|allow)', 'skip')
+    .option('--on-failure <channel>', 'Slack channel for failure alerts')
+    .option('--on-success <channel>', 'Slack channel for success alerts')
+    .option('-c, --config <path>', 'Path to config file')
+    .action((options) => {
+    const config = loadConfig(options.config);
+    const db = createConnection(config.dbPath);
+    runMigrations(db);
+    db.prepare(`INSERT INTO jobs (id, name, schedule, script, type, description, timeout_ms, overlap_policy, on_failure, on_success)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(options.id, options.name, options.schedule, resolve(options.script), options.type, options.description ?? null, options.timeout ? parseInt(options.timeout, 10) : null, options.overlap, options.onFailure ?? null, options.onSuccess ?? null);
+    console.log(`Job '${options.id}' added.`);
+    db.close();
+});
+program
+    .command('list-jobs')
+    .description('List all jobs')
+    .option('-c, --config <path>', 'Path to config file')
+    .action((options) => {
+    const config = loadConfig(options.config);
+    const db = createConnection(config.dbPath);
+    runMigrations(db);
+    const rows = db
+        .prepare('SELECT id, name, schedule, enabled FROM jobs')
+        .all();
+    if (rows.length === 0) {
+        console.log('No jobs configured.');
+    }
+    else {
+        for (const row of rows) {
+            const status = row.enabled ? '✅' : '⏸️';
+            console.log(`${status} ${row.id}  ${row.schedule}  ${row.name}`);
+        }
+    }
+    db.close();
+});
+program
+    .command('trigger')
+    .description('Manually trigger a job')
+    .requiredOption('-i, --id <id>', 'Job ID to trigger')
+    .option('-c, --config <path>', 'Path to config file')
+    .action((options) => {
+    const config = loadConfig(options.config);
+    void (async () => {
+        try {
+            const resp = await fetch(`http://127.0.0.1:${String(config.port)}/jobs/${options.id}/run`, { method: 'POST' });
+            const result = (await resp.json());
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch {
+            console.error(`Runner not reachable on port ${String(config.port)}. Is it running?`);
+            process.exit(1);
+        }
+    })();
+});
+program.parse();