@stonyx/cron 0.2.1-alpha.2 → 0.2.1-alpha.21

package/src/normalize.js

@@ -1,163 +0,0 @@
-/**
- * Input normalization for AI-generated job definitions.
- * Handles imperfect JSON from AI models: wrong casing, missing fields,
- * flat-param recovery, type coercion.
- */
-
-/**
- * Normalize a schedule object. Infers kind from fields if missing.
- */
-export function normalizeSchedule(raw) {
-  if (!raw || typeof raw !== 'object') return raw;
-
-  const schedule = { ...raw };
-
-  // Infer kind from fields if missing
-  if (!schedule.kind) {
-    if (schedule.at || schedule.atMs) schedule.kind = 'at';
-    else if (schedule.everyMs) schedule.kind = 'every';
-    else if (schedule.expr) schedule.kind = 'cron';
-  }
-
-  // Case normalization
-  if (typeof schedule.kind === 'string') {
-    schedule.kind = schedule.kind.toLowerCase();
-  }
-
-  // Legacy: atMs (number) → at (ISO string)
-  if (schedule.atMs && !schedule.at) {
-    schedule.at = new Date(schedule.atMs).toISOString();
-    delete schedule.atMs;
-  }
-
-  // Coerce string everyMs to number
-  if (typeof schedule.everyMs === 'string') {
-    schedule.everyMs = Number(schedule.everyMs);
-  }
-
-  return schedule;
-}
-
-/**
- * Normalize a payload object. Infers kind from fields if missing.
- */
-export function normalizePayload(raw) {
-  if (!raw || typeof raw !== 'object') return raw;
-
-  const payload = { ...raw };
-
-  // Infer kind from fields
-  if (!payload.kind) {
-    if (payload.message) payload.kind = 'agentTurn';
-    else if (payload.text) payload.kind = 'systemEvent';
-  }
-
-  // Case normalization
-  if (typeof payload.kind === 'string') {
-    const lower = payload.kind.toLowerCase();
-    if (lower === 'agentturn') payload.kind = 'agentTurn';
-    else if (lower === 'systemevent') payload.kind = 'systemEvent';
-  }
-
-  return payload;
-}
-
-/**
- * Recover a job object from flat parameters.
- * AI models sometimes flatten nested fields to the top level.
- */
-const JOB_KEYS = new Set([
-  'name', 'description', 'schedule', 'sessionTarget', 'payload',
-  'delivery', 'enabled', 'deleteAfterRun', 'wakeMode',
-]);
-
-export function recoverFlatParams(params) {
-  if (params.job && typeof params.job === 'object' && Object.keys(params.job).length > 0) {
-    return params.job;
-  }
-
-  const synthetic = {};
-  for (const key of Object.keys(params)) {
-    if (JOB_KEYS.has(key)) {
-      synthetic[key] = params[key];
-    }
-  }
-
-  // message/text are not JOB_KEYS but need to be recovered for payload wrapping
-  const message = params.message;
-  const text = params.text;
-
-  if (synthetic.schedule || synthetic.payload || message || text) {
-    // If message/text are at top level, wrap into payload
-    if (!synthetic.payload) {
-      if (message) {
-        synthetic.payload = { kind: 'agentTurn', message };
-      } else if (text) {
-        synthetic.payload = { kind: 'systemEvent', text };
-      }
-    }
-    return synthetic;
-  }
-
-  return params;
-}
-
-/**
- * Normalize a complete job input for creation.
- * Applies all normalization: schedule, payload, defaults.
- */
-export function normalizeJobInput(raw) {
-  const job = { ...raw };
-
-  if (job.schedule) {
-    job.schedule = normalizeSchedule(job.schedule);
-  }
-
-  if (job.payload) {
-    job.payload = normalizePayload(job.payload);
-  }
-
-  // Default: enabled
-  if (job.enabled === undefined) job.enabled = true;
-
-  // Default: wakeMode
-  if (!job.wakeMode) job.wakeMode = 'now';
-
-  // Default: sessionTarget inferred from payload
-  if (!job.sessionTarget && job.payload) {
-    job.sessionTarget = job.payload.kind === 'systemEvent' ? 'main' : 'isolated';
-  }
-
-  // Default: deleteAfterRun for one-shot
-  if (job.deleteAfterRun === undefined && job.schedule?.kind === 'at') {
-    job.deleteAfterRun = true;
-  }
-
-  // Default: delivery for isolated agentTurn
-  if (!job.delivery && job.sessionTarget === 'isolated' && job.payload?.kind === 'agentTurn') {
-    job.delivery = { mode: 'announce' };
-  }
-
-  // Auto-generate name if missing
-  if (!job.name) {
-    job.name = inferName(job);
-  }
-
-  return job;
-}
-
-/**
- * Infer a job name from schedule and payload.
- */
-function inferName(job) {
-  const parts = [];
-
-  if (job.schedule?.kind === 'at') parts.push('One-shot');
-  else if (job.schedule?.kind === 'every') parts.push('Recurring');
-  else if (job.schedule?.kind === 'cron') parts.push('Scheduled');
-
-  if (job.payload?.kind === 'agentTurn') parts.push('agent task');
-  else if (job.payload?.kind === 'systemEvent') parts.push('system event');
-
-  return parts.join(' ') || 'Unnamed job';
-}

package/src/run-log.js

@@ -1,79 +0,0 @@
-/**
- * In-memory run log for job execution history.
- * Stores recent execution results per job with auto-pruning.
- *
- * Persistence (via ORM) is added in PR 2.
- */
-
-const DEFAULT_MAX_ENTRIES_PER_JOB = 100;
-
-export default class RunLog {
-  constructor(maxEntriesPerJob = DEFAULT_MAX_ENTRIES_PER_JOB) {
-    this.maxEntries = maxEntriesPerJob;
-    this.entries = new Map(); // jobId → RunLogEntry[]
-  }
-
-  /**
-   * Record a job execution result.
-   *
-   * @param {object} entry
-   * @param {string} entry.jobId
-   * @param {"ok"|"error"|"skipped"} entry.status
-   * @param {string} [entry.error]
-   * @param {string} [entry.summary]
-   * @param {number} [entry.runAtMs]
-   * @param {number} [entry.durationMs]
-   * @param {number} [entry.nextRunAtMs]
-   */
-  record(entry) {
-    const log = {
-      ts: Date.now(),
-      jobId: entry.jobId,
-      status: entry.status,
-      error: entry.error,
-      summary: entry.summary,
-      runAtMs: entry.runAtMs,
-      durationMs: entry.durationMs,
-      nextRunAtMs: entry.nextRunAtMs,
-    };
-
-    if (!this.entries.has(entry.jobId)) {
-      this.entries.set(entry.jobId, []);
-    }
-
-    const logs = this.entries.get(entry.jobId);
-    logs.push(log);
-
-    // Auto-prune
-    if (logs.length > this.maxEntries) {
-      logs.splice(0, logs.length - this.maxEntries);
-    }
-  }
-
-  /**
-   * Get run history for a job.
-   *
-   * @param {string} jobId
-   * @param {number} [limit=20]
-   * @returns {object[]} Most recent entries, newest first
-   */
-  get(jobId, limit = 20) {
-    const logs = this.entries.get(jobId);
-    if (!logs) return [];
-    return logs.slice(-limit).reverse();
-  }
-
-  /**
-   * Remove all entries for a job.
-   */
-  removeJob(jobId) {
-    this.entries.delete(jobId);
-  }
-
-  /**
-   * Clear all entries.
-   */
-  clear() {
-    this.entries.clear();
-  }
-}

package/src/schedule.js

@@ -1,81 +0,0 @@
-/**
- * Schedule types and next-run computation.
- *
- * Three schedule kinds:
- *   - "at": One-shot at an absolute ISO-8601 timestamp
- *   - "every": Recurring interval in milliseconds
- *   - "cron": 5-field cron expression with optional timezone
- */
-import { nextOccurrence, validateCronExpression } from './cron-parser.js';
-
-/**
- * Compute the next run time for a schedule.
- *
- * @param {object} schedule - Schedule definition
- * @param {string} schedule.kind - "at" | "every" | "cron"
- * @param {number} nowMs - Current time in milliseconds
- * @returns {number|undefined} Next run time in ms, or undefined if no future occurrence
- */
-export function computeNextRunAtMs(schedule, nowMs) {
-  if (schedule.kind === 'at') {
-    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
-    if (!Number.isFinite(atMs)) return undefined;
-    return atMs > nowMs ? atMs : undefined;
-  }
-
-  if (schedule.kind === 'every') {
-    const everyMs = Math.max(1, Math.floor(schedule.everyMs));
-    const anchor = Math.max(0, Math.floor(schedule.anchorMs ?? nowMs));
-
-    if (nowMs < anchor) return anchor;
-
-    const elapsed = nowMs - anchor;
-    const steps = Math.max(1, Math.floor((elapsed + everyMs - 1) / everyMs));
-    return anchor + steps * everyMs;
-  }
-
-  if (schedule.kind === 'cron') {
-    const tz = schedule.tz?.trim() || undefined;
-    // Round nowMs down to the current second to avoid sub-second drift
-    const nowSecondMs = Math.floor(nowMs / 1000) * 1000;
-    return nextOccurrence(schedule.expr.trim(), nowSecondMs, tz);
-  }
-
-  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
-}
-
-/**
- * Validate a schedule definition.
- * @param {object} schedule
- * @throws {Error} if the schedule is invalid
- */
-export function validateSchedule(schedule) {
-  if (!schedule || typeof schedule !== 'object') {
-    throw new Error('Schedule must be an object');
-  }
-
-  if (schedule.kind === 'at') {
-    const atMs = typeof schedule.at === 'number' ? schedule.at : Date.parse(schedule.at);
-    if (!Number.isFinite(atMs)) {
-      throw new Error(`Invalid "at" timestamp: "${schedule.at}"`);
-    }
-    return;
-  }
-
-  if (schedule.kind === 'every') {
-    if (typeof schedule.everyMs !== 'number' || schedule.everyMs < 1) {
-      throw new Error(`"every" schedule requires everyMs >= 1, got: ${schedule.everyMs}`);
-    }
-    return;
-  }
-
-  if (schedule.kind === 'cron') {
-    if (typeof schedule.expr !== 'string' || !schedule.expr.trim()) {
-      throw new Error('"cron" schedule requires a non-empty expr string');
-    }
-    validateCronExpression(schedule.expr.trim());
-    return;
-  }
-
-  throw new Error(`Unknown schedule kind: "${schedule.kind}"`);
-}

package/src/service.js

@@ -1,303 +0,0 @@
-/**
- * CronService — the main API for advanced job scheduling.
- *
- * Manages jobs in memory with a min-heap for efficient next-job lookup.
- * Supports pluggable store interface (memory-only by default, ORM in PR 2).
- * All state mutations are serialized via async locking.
- */
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import MinHeap from './min-heap.js';
-import { createJob, updateJob, markRunning, applyResult, isDue } from './job.js';
-import { computeNextRunAtMs } from './schedule.js';
-import { locked } from './locked.js';
-import { normalizeJobInput, recoverFlatParams } from './normalize.js';
-import RunLog from './run-log.js';
-
-const MAX_TIMER_DELAY_MS = 60_000;
-
-export default class CronService {
-  constructor() {
-    this.jobs = new Map();       // id → job
-    this.heap = new MinHeap();   // ordered by nextRunAtMs
-    this.timer = null;
-    this.running = false;
-    this.runLog = new RunLog();
-    this.started = false;
-
-    // Pluggable callbacks for consumers
-    this.onJobDue = null;        // async (job) => { status, error?, summary? }
-  }
-
-  // ── Lifecycle ──────────────────────────────────────────────
-
-  /**
-   * Start the service. Loads jobs from store (if any), arms timer.
-   */
-  async start(initialJobs) {
-    if (this.started) return;
-    this.started = true;
-
-    if (initialJobs) {
-      for (const job of initialJobs) {
-        this.jobs.set(job.id, job);
-        if (job.enabled && job.state.nextRunAtMs) {
-          this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-        }
-      }
-    }
-
-    this.armTimer();
-  }
-
-  /**
-   * Stop the service. Clears timer.
-   */
-  stop() {
-    this.started = false;
-    clearTimeout(this.timer);
-    this.timer = null;
-  }
-
-  // ── CRUD ───────────────────────────────────────────────────
-
-  /**
-   * Get service status.
-   */
-  status() {
-    const peek = this.heap.peek();
-    return {
-      started: this.started,
-      jobCount: this.jobs.size,
-      nextWakeAtMs: peek ? peek.nextTrigger : undefined,
-    };
-  }
-
-  /**
-   * List jobs, optionally including disabled ones.
-   */
-  list(opts) {
-    const includeDisabled = opts?.includeDisabled ?? false;
-    const jobs = [...this.jobs.values()];
-    const filtered = includeDisabled ? jobs : jobs.filter(j => j.enabled);
-    return filtered.sort((a, b) => (a.state.nextRunAtMs ?? Infinity) - (b.state.nextRunAtMs ?? Infinity));
-  }
-
-  /**
-   * Get a single job by ID.
-   */
-  get(id) {
-    return this.jobs.get(id) || null;
-  }
-
-  /**
-   * Add a new job. Input is normalized for AI compatibility.
-   */
-  async add(rawInput) {
-    return locked(() => {
-      const input = normalizeJobInput(recoverFlatParams(rawInput));
-      const job = createJob(input);
-      this.jobs.set(job.id, job);
-
-      if (job.enabled && job.state.nextRunAtMs) {
-        this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-        this.armTimer();
-      }
-
-      return job;
-    });
-  }
-
-  /**
-   * Update an existing job.
-   */
-  async update(id, patch) {
-    return locked(() => {
-      const job = this.jobs.get(id);
-      if (!job) throw new Error(`Job not found: ${id}`);
-
-      const oldNextRun = job.state.nextRunAtMs;
-      updateJob(job, patch);
-
-      // Update heap entry
-      this.removeFromHeap(id);
-      if (job.enabled && job.state.nextRunAtMs) {
-        this.heap.push({ key: id, nextTrigger: job.state.nextRunAtMs });
-      }
-
-      if (job.state.nextRunAtMs !== oldNextRun) {
-        this.armTimer();
-      }
-
-      return job;
-    });
-  }
-
-  /**
-   * Remove a job.
-   */
-  async remove(id) {
-    return locked(() => {
-      const job = this.jobs.get(id);
-      if (!job) throw new Error(`Job not found: ${id}`);
-
-      this.jobs.delete(id);
-      this.removeFromHeap(id);
-      this.runLog.removeJob(id);
-      this.armTimer();
-    });
-  }
-
-  /**
-   * Manually trigger a job.
-   *
-   * @param {string} id - Job ID
-   * @param {"due"|"force"} [mode="force"] - "due" only runs if the job is due, "force" runs regardless
-   */
-  async run(id, mode = 'force') {
-    const job = this.jobs.get(id);
-    if (!job) throw new Error(`Job not found: ${id}`);
-
-    if (mode === 'due' && !isDue(job, Date.now())) {
-      return { status: 'skipped', reason: 'not due' };
-    }
-
-    return this.executeJob(job);
-  }
-
-  /**
-   * Get run history for a job.
-   */
-  runs(id, limit) {
-    return this.runLog.get(id, limit);
-  }
-
-  // ── Timer Engine ──────────────────────────────────────��────
-
-  armTimer() {
-    clearTimeout(this.timer);
-    if (!this.started) return;
-
-    const peek = this.heap.peek();
-    if (!peek) return;
-
-    const delay = Math.min(Math.max(peek.nextTrigger - Date.now(), 0), MAX_TIMER_DELAY_MS);
-    this.timer = setTimeout(() => this.onTimer(), delay);
-  }
-
-  async onTimer() {
-    if (this.running) {
-      // Already processing — re-arm at max delay to prevent scheduler death
-      this.timer = setTimeout(() => this.onTimer(), MAX_TIMER_DELAY_MS);
-      return;
-    }
-
-    this.running = true;
-
-    try {
-      await locked(async () => {
-        const nowMs = Date.now();
-        const dueJobs = this.findDueJobs(nowMs);
-
-        for (const job of dueJobs) {
-          markRunning(job);
-        }
-
-        for (const job of dueJobs) {
-          await this.executeJob(job);
-        }
-      });
-    } finally {
-      this.running = false;
-      this.armTimer();
-    }
-  }
-
-  findDueJobs(nowMs) {
-    const due = [];
-
-    while (!this.heap.isEmpty()) {
-      const peek = this.heap.peek();
-      if (peek.nextTrigger > nowMs) break;
-
-      this.heap.pop();
-      const job = this.jobs.get(peek.key);
-      if (job && isDue(job, nowMs)) {
-        due.push(job);
-      }
-    }
-
-    return due;
-  }
-
-  async executeJob(job) {
-    const startMs = Date.now();
-    let status = 'ok';
-    let error;
-    let summary;
-
-    try {
-      if (this.onJobDue) {
-        const result = await this.onJobDue(job);
-        if (result) {
-          status = result.status || 'ok';
-          error = result.error;
-          summary = result.summary;
-        }
-      }
-    } catch (err) {
-      status = 'error';
-      error = err?.message || String(err);
-      this.log(`Job "${job.name}" (${job.id}) failed: ${error}`);
-    }
-
-    const durationMs = Date.now() - startMs;
-
-    applyResult(job, status, error, durationMs);
-
-    // Log the run
-    this.runLog.record({
-      jobId: job.id,
-      status,
-      error,
-      summary,
-      runAtMs: startMs,
-      durationMs,
-      nextRunAtMs: job.state.nextRunAtMs,
-    });
-
-    // Handle one-shot auto-delete
-    if (job.deleteAfterRun && status === 'ok' && !job.enabled) {
-      this.jobs.delete(job.id);
-      this.runLog.removeJob(job.id);
-      return { status, summary, deleted: true };
-    }
-
-    // Re-insert into heap if still active
-    if (job.enabled && job.state.nextRunAtMs) {
-      this.heap.push({ key: job.id, nextTrigger: job.state.nextRunAtMs });
-    }
-
-    return { status, error, summary, durationMs };
-  }
-
-  // ── Helpers ────────────────────────────────────────────────
-
-  removeFromHeap(id) {
-    // MinHeap doesn't support remove-by-key efficiently,
-    // so we rebuild. Fine for typical job counts (< 1000).
-    const remaining = [];
-    while (!this.heap.isEmpty()) {
-      const item = this.heap.pop();
-      if (item.key !== id) remaining.push(item);
-    }
-    for (const item of remaining) {
-      this.heap.push(item);
-    }
-  }
-
-  log(message) {
-    if (!config.cron?.log) return;
-    log.cron(`Cron — ${message}`);
-  }
-}

package/stonyx-bootstrap.cjs

@@ -1,9 +0,0 @@
-/**
- * commonJS Bootstrap loading - Stonyx must be loaded first, prior to the rest of the application
- */
-const { default:Stonyx } = require('stonyx');
-const { default:config } = require('./config/environment.js');
-
-new Stonyx(config, __dirname);
-
-module.exports = Stonyx;