@karmaniverous/jeeves-runner 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -11,6 +11,7 @@ import { DatabaseSync } from 'node:sqlite';
 /** Full runner configuration schema. Validates and provides defaults. */
 declare const runnerConfigSchema: z.ZodObject<{
     port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
     dbPath: z.ZodDefault<z.ZodString>;
     maxConcurrency: z.ZodDefault<z.ZodNumber>;
     runRetentionDays: z.ZodDefault<z.ZodNumber>;
@@ -24,11 +25,11 @@ declare const runnerConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     log: z.ZodDefault<z.ZodObject<{
         level: z.ZodDefault<z.ZodEnum<{
-            error: "error";
             trace: "trace";
             debug: "debug";
             info: "info";
             warn: "warn";
+            error: "error";
             fatal: "fatal";
         }>>;
         file: z.ZodOptional<z.ZodString>;
@@ -62,7 +63,6 @@ declare const jobSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     overlapPolicy: z.ZodDefault<z.ZodEnum<{
         skip: "skip";
-        queue: "queue";
         allow: "allow";
     }>>;
     onFailure: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -103,9 +103,9 @@ type Queue = z.infer<typeof queueSchema>;
 /** Run status enumeration schema (pending, running, ok, error, timeout, skipped). */
 declare const runStatusSchema: z.ZodEnum<{
     pending: "pending";
+    error: "error";
     running: "running";
     ok: "ok";
-    error: "error";
     timeout: "timeout";
     skipped: "skipped";
 }>;
@@ -121,9 +121,9 @@ declare const runSchema: z.ZodObject<{
     jobId: z.ZodString;
     status: z.ZodEnum<{
         pending: "pending";
+        error: "error";
         running: "running";
         ok: "ok";
-        error: "error";
         timeout: "timeout";
         skipped: "skipped";
     }>;
@@ -151,6 +151,8 @@ type RunTrigger = z.infer<typeof runTriggerSchema>;
 
 /**
  * Main runner orchestrator. Wires up database, scheduler, API server, and handles graceful shutdown on SIGTERM/SIGINT.
+ *
+ * @module
  */
 
 /** Runner interface for managing the runner lifecycle. */
@@ -172,6 +174,8 @@ declare function createRunner(config: RunnerConfig, deps?: RunnerDeps): Runner;
 
 /**
  * Queue operations module for runner client. Provides enqueue, dequeue, done, and fail operations.
+ *
+ * @module
  */
 
 /** Queue item returned from dequeue operation. */
@@ -184,6 +188,8 @@ interface QueueItem {
 
 /**
  * Job client library for runner jobs. Provides state and queue operations. Opens its own DB connection via JR_DB_PATH env var.
+ *
+ * @module
  */
 
 /** Client interface for job scripts to interact with runner state and queues. */
@@ -238,6 +244,8 @@ declare function createClient(dbPath?: string): RunnerClient;
 
 /**
  * Job executor. Spawns job scripts as child processes, captures output, parses result metadata, enforces timeouts.
+ *
+ * @module
  */
 /** Result of a job execution. */
 interface ExecutionResult {
@@ -279,6 +287,8 @@ interface ExecutionOptions {
     timeoutMs?: number;
     /** Optional custom command resolver (for extensibility). */
     commandResolver?: (script: string) => ResolvedCommand;
+    /** Source type: 'path' uses script as file path, 'inline' writes script content to a temp file. */
+    sourceType?: 'path' | 'inline';
 }
 /**
  * Execute a job script as a child process. Captures output, parses metadata, enforces timeout.
@@ -287,6 +297,8 @@ declare function executeJob(options: ExecutionOptions): Promise<ExecutionResult>
 
 /**
  * OpenClaw Gateway HTTP client for spawning and monitoring sessions.
+ *
+ * @module
  */
 /** Options for creating a Gateway client. */
 interface GatewayClientOptions {
@@ -345,6 +357,8 @@ declare function createGatewayClient(options: GatewayClientOptions): GatewayClie
 
 /**
  * Slack notification module. Sends job completion/failure messages via Slack Web API (chat.postMessage). Falls back gracefully if no token.
+ *
+ * @module
  */
 /** Notification configuration. */
 interface NotifyConfig {
@@ -375,7 +389,9 @@ interface Notifier {
 declare function createNotifier(config: NotifyConfig): Notifier;
 
 /**
- * Croner-based job scheduler. Loads enabled jobs, creates cron instances, manages execution, respects overlap policies and concurrency limits.
+ * Job scheduler. Loads enabled jobs, registers schedules (cron or rrstack), manages execution, respects overlap policies and concurrency limits.
+ *
+ * @module
  */
 
 /** Scheduler dependencies. */
@@ -413,8 +429,47 @@ interface Scheduler {
  */
 declare function createScheduler(deps: SchedulerDeps): Scheduler;
 
+/**
+ * Schedule parsing, validation, and next-fire-time computation for cron and RRStack formats.
+ *
+ * @module
+ */
+/** Successful schedule validation result. */
+interface ScheduleValid {
+    /** Whether the schedule is valid. */
+    valid: true;
+    /** Detected schedule format. */
+    format: 'cron' | 'rrstack';
+}
+/** Failed schedule validation result. */
+interface ScheduleInvalid {
+    /** Whether the schedule is valid. */
+    valid: false;
+    /** Descriptive error message. */
+    error: string;
+}
+/** Validation result for a schedule string. */
+type ScheduleValidation = ScheduleValid | ScheduleInvalid;
+/**
+ * Compute the next fire time for a schedule string.
+ * Supports cron expressions (via croner) and RRStack JSON (via nextEvent).
+ *
+ * @param schedule - Cron expression or RRStack JSON string.
+ * @returns Next fire time as a Date, or null if none can be determined.
+ */
+declare function getNextFireTime(schedule: string): Date | null;
+/**
+ * Validate a schedule string as either a cron expression or RRStack JSON.
+ *
+ * @param schedule - Cron expression or RRStack JSON string.
+ * @returns Validation result with format on success, or error message on failure.
+ */
+declare function validateSchedule(schedule: string): ScheduleValidation;
+
 /**
  * Session executor for job type='session'. Spawns OpenClaw Gateway sessions and polls for completion.
+ *
+ * @module
  */
 
 /** Options for executing a session job. */
@@ -437,6 +492,8 @@ declare function executeSession(options: SessionExecutionOptions): Promise<Execu
 
 /**
  * SQLite connection manager. Creates DB file with parent directories, enables WAL mode for concurrency.
+ *
+ * @module
  */
 
 /**
@@ -451,6 +508,8 @@ declare function closeConnection(db: DatabaseSync): void;
 
 /**
  * Database maintenance tasks: run retention pruning and expired state cleanup.
+ *
+ * @module
  */
 
 /** Configuration for maintenance tasks. */
@@ -476,6 +535,8 @@ declare function createMaintenance(db: DatabaseSync, config: MaintenanceConfig,
 
 /**
  * Schema migration runner. Tracks applied migrations via schema_version table, applies pending migrations idempotently.
+ *
+ * @module
  */
 
 /**
@@ -483,5 +544,5 @@ declare function createMaintenance(db: DatabaseSync, config: MaintenanceConfig,
  */
 declare function runMigrations(db: DatabaseSync): void;
 
-export { closeConnection, createClient, createConnection, createGatewayClient, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, executeSession, jobSchema, queueSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema };
-export type { ExecutionOptions, ExecutionResult, GatewayClient, GatewayClientOptions, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, NotifyLogger, Queue, QueueItem, ResolvedCommand, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, RunnerDeps, Scheduler, SchedulerDeps, SessionExecutionOptions, SessionInfo, SessionMessage, SpawnSessionOptions, SpawnSessionResult };
+export { closeConnection, createClient, createConnection, createGatewayClient, createMaintenance, createNotifier, createRunner, createScheduler, executeJob, executeSession, getNextFireTime, jobSchema, queueSchema, runMigrations, runSchema, runStatusSchema, runTriggerSchema, runnerConfigSchema, validateSchedule };
+export type { ExecutionOptions, ExecutionResult, GatewayClient, GatewayClientOptions, Job, Maintenance, MaintenanceConfig, Notifier, NotifyConfig, NotifyLogger, Queue, QueueItem, ResolvedCommand, Run, RunStatus, RunTrigger, Runner, RunnerClient, RunnerConfig, RunnerDeps, ScheduleInvalid, ScheduleValid, ScheduleValidation, Scheduler, SchedulerDeps, SessionExecutionOptions, SessionInfo, SessionMessage, SpawnSessionOptions, SpawnSessionResult };