sails-hook-quest 0.0.4 → 0.0.6

package/lib/core/runtime.js

@@ -0,0 +1,240 @@
+// @ts-check
+const { randomUUID } = require('node:crypto')
+const { encodeResult } = require('./result')
+const { effectiveTimezone } = require('./scheduler')
+
+function createRuntime() {
+  return { runtimeId: randomUUID(), sequence: 0, active: new Map() }
+}
+
+/** @param {import('../types').QuestContext} context */
+function runtimeInfo(context) {
+  return {
+    contractVersion: 1,
+    runtimeId: context.runtime.runtimeId,
+    scope: 'process',
+    capabilities: {
+      inputMetadata: true,
+      runIdentity: true,
+      businessResults: true,
+      residentState: true,
+      childSchedulerSuppression: true,
+      triggerProvenance: true,
+      terminalExitCode: true,
+      terminalSignal: true,
+      scheduleDiagnostics: true,
+      cancellation: false,
+      durableHistory: false
+    }
+  }
+}
+
+const fields = [
+  'type',
+  'description',
+  'friendlyName',
+  'required',
+  'allowNull',
+  'isIn',
+  'min',
+  'max',
+  'minLength',
+  'maxLength',
+  'isEmail',
+  'isURL',
+  'isInteger',
+  'regex',
+  'example'
+]
+/** @param {import('../types').QuestMachineInputs} [schema] */
+function inputMetadata(schema = {}) {
+  const result = Object.create(null)
+  for (const [name, def] of Object.entries(schema)) {
+    if (!def || typeof def !== 'object') continue
+    const field = Object.create(null)
+    field.sensitive = Boolean(
+      def.protect ||
+        def.secret ||
+        def.sensitive ||
+        /password|secret|token|credential/i.test(name)
+    )
+    field.customValidation = typeof def.custom === 'function'
+    for (const key of fields) {
+      if (field.sensitive && key === 'example') continue
+      if (Object.prototype.hasOwnProperty.call(def, key)) {
+        const encoded = encodeResult(def[key], 4096)
+        if (encoded.status === 'available') field[key] = encoded.value
+      }
+    }
+    if (
+      !field.sensitive &&
+      Object.prototype.hasOwnProperty.call(def, 'defaultsTo')
+    ) {
+      const encoded = encodeResult(def.defaultsTo, 4096)
+      if (encoded.status === 'available') field.defaultsTo = encoded.value
+    }
+    result[name] = field
+  }
+  return result
+}
+
+/** Describe the raw effective scheduled values; validation is still Sails' authority.
+ * @param {import('../types').QuestJob} job
+ */
+function scheduledInputs(job) {
+  const schema = job.inputSchema || {}
+  const safeSchema = inputMetadata(schema)
+  const configured = job.inputs || {}
+  const scriptInputs = job.scriptInputs || {}
+  const names = new Set([
+    ...Object.keys(schema),
+    ...Object.keys(configured),
+    ...Object.keys(scriptInputs)
+  ])
+  const values = Object.create(null)
+  const fields = Object.create(null)
+  let remaining = 64 * 1024
+  for (const name of names) {
+    const own = (object) => Object.prototype.hasOwnProperty.call(object, name)
+    const source = own(scriptInputs)
+      ? 'script_input'
+      : own(configured)
+        ? 'job_input'
+        : schema[name]?.defaultsTo !== undefined
+          ? 'schema_default'
+          : 'omitted'
+    const value =
+      source === 'script_input'
+        ? scriptInputs[name]
+        : source === 'job_input'
+          ? configured[name]
+          : source === 'schema_default'
+            ? schema[name].defaultsTo
+            : undefined
+    const sensitive =
+      safeSchema[name]?.sensitive ||
+      /password|secret|token|credential/i.test(name)
+    /** @type {import('../types').AnyRecord} */
+    const field = {
+      source,
+      sensitive: Boolean(sensitive),
+      available: false,
+      missingRequired: Boolean(schema[name]?.required && value === undefined)
+    }
+    if (value !== undefined && !sensitive) {
+      const encoded = encodeResult(
+        value,
+        Math.max(1, Math.min(4096, remaining))
+      )
+      if (
+        encoded.status === 'available' &&
+        Buffer.byteLength(encoded.json) <= remaining
+      ) {
+        values[name] = encoded.value
+        field.available = true
+        remaining -= Buffer.byteLength(encoded.json)
+      } else
+        field.reason =
+          encoded.status === 'available' ? 'metadata_limit' : encoded.status
+    } else if (sensitive) field.reason = 'sensitive'
+    fields[name] = field
+  }
+  return { values, fields, validation: 'not_checked', limitBytes: 64 * 1024 }
+}
+
+/** Mirror parser precedence; unused lower-priority fields do not change restart semantics. */
+function restartSemantics(job) {
+  let timing = 'none'
+  let oneShot = false
+  if (job.cron) timing = 'wall_clock'
+  else if (job.interval !== undefined && job.interval !== false)
+    timing =
+      typeof job.interval === 'string' && /at|on the/.test(job.interval)
+        ? 'wall_clock'
+        : 'relative_to_registration'
+  else if (job.timeout !== undefined && job.timeout !== false) {
+    timing =
+      typeof job.timeout === 'string' && job.timeout.startsWith('at ')
+        ? 'wall_clock'
+        : 'relative_to_registration'
+    oneShot = true
+  } else if (job.date !== undefined && job.date !== false) {
+    timing = 'wall_clock'
+    oneShot = true
+  }
+  return {
+    persistence: 'memory_only',
+    timing,
+    oneShot,
+    missedRuns: 'not_replayed'
+  }
+}
+
+/** @param {import('../types').QuestContext} context @param {string} [name] */
+function metadata(context, name) {
+  const describe = (job) => {
+    const schedule = {}
+    for (const key of [
+      'interval',
+      'cron',
+      'cronOptions',
+      'timeout',
+      'date',
+      'timezone'
+    ]) {
+      if (job[key] !== undefined) {
+        const encoded = encodeResult(
+          job[key] instanceof Date
+            ? Number.isFinite(job[key].getTime())
+              ? job[key].toISOString()
+              : null
+            : job[key],
+          4096
+        )
+        if (encoded.status === 'available') schedule[key] = encoded.value
+      }
+    }
+    schedule.timezone = effectiveTimezone(job, context.config || {})
+    return {
+      name: job.name,
+      script: job.script || job.name,
+      friendlyName: job.friendlyName,
+      description: job.description,
+      inputMetadataAvailable: Boolean(job.inputSchema),
+      inputs: inputMetadata(job.inputSchema),
+      scheduledInputs: scheduledInputs(job),
+      schedule,
+      scheduleState: {
+        registration: 'not_attempted',
+        validation: 'not_checked',
+        reason: null,
+        lastAttemptAt: null,
+        ...context.scheduleStates?.get(job.name),
+        validationErrors: (
+          context.scheduleStates?.get(job.name)?.validationErrors || []
+        ).map(({ code, message }) => ({ code, message })),
+        restart: restartSemantics(job)
+      },
+      paused: job.paused,
+      withoutOverlapping: job.withoutOverlapping,
+      runningCount: context.runtime.active.get(job.name)?.size || 0,
+      scheduled: context.timers.has(job.name),
+      nextRunAt: context.timers.has(job.name)
+        ? context.dueTimes.get(job.name)?.toISOString() || null
+        : null,
+      runtimeId: context.runtime.runtimeId
+    }
+  }
+  if (name !== undefined) {
+    const job = context.jobs.get(name)
+    return job ? describe(job) : undefined
+  }
+  return Array.from(context.jobs.values(), describe)
+}
+module.exports = {
+  createRuntime,
+  runtimeInfo,
+  inputMetadata,
+  scheduledInputs,
+  metadata
+}

package/lib/core/scheduler.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * core/scheduler.js
  *
@@ -7,75 +9,120 @@
 const later = require('@breejs/later')
 const humanInterval = require('human-interval')
 const { CronExpressionParser } = require('cron-parser')
+const { getGlobalSails } = require('./global-sails')
+
+/** @typedef {import('../types').QuestConfig} QuestConfig */
+/** @typedef {import('../types').QuestJobDefinition} QuestJobDefinition */
+/** @typedef {import('../types').QuestTimeout} QuestTimeout */
 
 /**
  * Parse various schedule formats and return next run time
- * @param {Object} job - Job configuration
- * @param {Object} config - Quest configuration
+ * @param {QuestJobDefinition} job - Job configuration
+ * @param {QuestConfig} [config] - Quest configuration
+ * @param {(assessment: import('../types').AnyRecord) => void} [report] Bounded parser assessment
  * @returns {Date|null} Next run time or null if invalid
  */
-function getNextRunTime(job, config = {}) {
+function getNextRunTime(job, config = {}, report = () => {}) {
   const now = new Date()
-  const timezone = job.timezone || config.timezone
+  const assess = (nextRun, validation, reason = null, code = null) => {
+    report({
+      validation,
+      reason,
+      validationErrors: code
+        ? [{ code, message: scheduleErrorMessages[code] }]
+        : []
+    })
+    return nextRun
+  }
+  const invalid = (code) => assess(null, 'invalid', null, code)
 
-  // Validate: cannot combine date and timeout
+  // Preserve the existing conflict exception, but retain its assessment first.
   if (job.date && job.timeout !== undefined && job.timeout !== false) {
+    invalid('E_SCHEDULE_CONFLICT')
     throw new Error(
       `Job "${job.name}": Cannot combine 'date' and 'timeout'. Use one or the other.`
     )
   }
-
-  // Handle cron expressions
   if (job.cron) {
+    let interval
     try {
-      const options = { tz: timezone }
-      // Merge any cron-parser options (currentDate, startDate, endDate, etc.)
-      if (job.cronOptions) {
-        Object.assign(options, job.cronOptions)
-      }
-      const interval = CronExpressionParser.parse(job.cron, options)
-      return interval.next().toDate()
+      const options = { tz: effectiveTimezone(job, config) }
+      if (job.cronOptions) Object.assign(options, job.cronOptions)
+      interval = CronExpressionParser.parse(job.cron, options)
     } catch (err) {
-      if (global.sails) {
-        sails.log.error(
-          `Invalid cron expression for job "${job.name}": ${job.cron}`,
-          err.message
-        )
-      }
-      return null
+      const sails = getGlobalSails()
+      if (sails) sails.log.error(`Invalid cron schedule for job "${job.name}"`)
+      return invalid('E_SCHEDULE_CRON')
     }
-  }
-
-  // Handle human-readable intervals
-  if (job.interval && typeof job.interval === 'string') {
-    const nextTime = parseInterval(job.interval, now)
-    if (nextTime) return nextTime
-
-    if (global.sails) {
-      sails.log.error(`Invalid interval for job "${job.name}": ${job.interval}`)
+    try {
+      return assess(interval.next().toDate(), 'valid')
+    } catch (err) {
+      // A parsed cron can be exhausted by its endDate; that is not invalid.
+      return assess(null, 'valid', 'no_future_run')
     }
-    return null
   }
-
-  // Handle numeric intervals (milliseconds)
-  if (typeof job.interval === 'number') {
-    return new Date(now.getTime() + job.interval)
+  if (job.interval !== undefined && job.interval !== false) {
+    let nextTime = null
+    if (typeof job.interval === 'string')
+      nextTime = parseInterval(job.interval, now)
+    if (
+      typeof job.interval === 'number' &&
+      Number.isFinite(job.interval) &&
+      job.interval > 0
+    )
+      nextTime = new Date(now.getTime() + job.interval)
+    if (!nextTime || !Number.isFinite(nextTime.getTime()) || nextTime <= now)
+      return invalid('E_SCHEDULE_INTERVAL')
+    return assess(nextTime, 'valid')
   }
-
-  // Handle timeout (one-time delay)
   if (job.timeout !== undefined && job.timeout !== false) {
-    return parseTimeout(job.timeout, now)
+    if (
+      typeof job.timeout === 'number' &&
+      (!Number.isFinite(job.timeout) || job.timeout < 0)
+    )
+      return invalid('E_SCHEDULE_TIMEOUT')
+    const nextTime = parseTimeout(job.timeout, now)
+    if (!nextTime || !Number.isFinite(nextTime.getTime()) || nextTime < now)
+      return invalid('E_SCHEDULE_TIMEOUT')
+    return assess(nextTime, 'valid')
   }
-
-  // Handle specific date
-  if (job.date) {
+  if (job.date !== undefined && job.date !== false) {
+    if (
+      !(job.date instanceof Date) &&
+      typeof job.date !== 'string' &&
+      typeof job.date !== 'number'
+    )
+      return invalid('E_SCHEDULE_DATE')
     const date = new Date(job.date)
-    if (date > now) {
-      return date
-    }
+    if (!Number.isFinite(date.getTime())) return invalid('E_SCHEDULE_DATE')
+    return assess(
+      date > now ? date : null,
+      'valid',
+      date > now ? null : 'no_future_run'
+    )
   }
+  return assess(null, 'not_checked', 'no_schedule')
+}
 
-  return null
+const scheduleErrorMessages = {
+  E_SCHEDULE_CONFLICT: 'Date and timeout cannot be combined.',
+  E_SCHEDULE_CRON: 'Cron expression, timezone, or parser options are invalid.',
+  E_SCHEDULE_INTERVAL:
+    'Interval must produce a finite future time; numeric intervals must be positive.',
+  E_SCHEDULE_TIMEOUT:
+    'Timeout must produce a finite time; numeric timeouts must be nonnegative.',
+  E_SCHEDULE_DATE: 'Date must be a supported finite date value.'
+}
+
+/** Use the same precedence as cron-parser registration, including explicit tz overrides.
+ * @param {QuestJobDefinition} job @param {QuestConfig} [config]
+ */
+function effectiveTimezone(job, config = {}) {
+  return job.cron &&
+    job.cronOptions &&
+    Object.prototype.hasOwnProperty.call(job.cronOptions, 'tz')
+    ? job.cronOptions.tz || null
+    : job.timezone || config.timezone || null
 }
 
 /**
@@ -95,6 +142,7 @@ function parseInterval(intervalStr, fromDate = new Date()) {
   if (everyMatch) {
     const amount = parseInt(everyMatch[1])
     const unit = everyMatch[2].replace(/s$/, '') // Remove plural 's'
+    /** @type {Record<string, number>} */
     const msMap = {
       second: 1000,
       minute: 60000,
@@ -138,7 +186,7 @@ function parseInterval(intervalStr, fromDate = new Date()) {
 
 /**
  * Parse a timeout value into a Date
- * @param {String|Number} timeout - Timeout value
+ * @param {QuestTimeout} timeout - Timeout value
  * @param {Date} fromDate - Calculate from this date
  * @returns {Date|null} Next run time or null
  */
@@ -197,6 +245,7 @@ function convertShorthand(str) {
 
 module.exports = {
   getNextRunTime,
+  effectiveTimezone,
   parseInterval,
   parseTimeout,
   convertShorthand

package/lib/index.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * sails-hook-quest
  *
@@ -9,17 +11,45 @@ const scheduler = require('./core/scheduler')
 const executor = require('./core/executor')
 const loader = require('./core/loader')
 const jobControl = require('./core/job-control')
+const resident = require('./core/runtime')
+const { isExecutionChild } = require('./core/execution-child')
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').QuestApi} QuestApi */
+/** @typedef {import('./types').QuestConfig} QuestConfig */
+/** @typedef {import('./types').QuestContext} QuestContext */
+/** @typedef {import('./types').QuestExecutableJob} QuestExecutableJob */
+/** @typedef {import('./types').QuestJobsMap} QuestJobsMap */
+/** @typedef {import('./types').QuestNamedJobDefinition} QuestNamedJobDefinition */
+/** @typedef {import('./types').QuestRunningMap} QuestRunningMap */
+/** @typedef {import('./types').QuestSailsApp} QuestSailsApp */
+/** @typedef {import('./types').QuestSailsHook} QuestSailsHook */
+/** @typedef {import('./types').QuestTimersMap} QuestTimersMap */
 
-module.exports = function defineQuestHook(sails) {
+/**
+ * Sails hook factory.
+ *
+ * @param {QuestSailsApp} sails
+ * @returns {QuestSailsHook}
+ */
+function defineQuestHook(sails) {
+  /** @type {QuestJobsMap} */
   const jobs = new Map()
+  /** @type {QuestTimersMap} */
   const timers = new Map()
+  /** @type {QuestRunningMap} */
   const running = new Map()
 
   // Create context object that will be passed to modules
+  /** @type {QuestContext} */
   const context = {
     jobs,
     timers,
     running,
+    sails,
+    runtime: resident.createRuntime(),
+    dueTimes: new Map(),
+    scheduleStates: new Map(),
     config: null, // Will be set after sails.config is available
     scheduleJob: null, // Will be set after function is defined
     executeJob: null, // Will be set after function is defined
@@ -47,6 +77,12 @@ module.exports = function defineQuestHook(sails) {
         // Directory containing job scripts
         scriptsDir: 'scripts',
 
+        // Maximum child output retained on failure (live output remains unbounded)
+        diagnosticTailBytes: 64 * 1024,
+
+        resultBytes: 64 * 1024,
+        inputBytes: 64 * 1024,
+
         // Jobs defined in config
         jobs: []
       }
@@ -55,36 +91,64 @@ module.exports = function defineQuestHook(sails) {
     initialize: async function () {
       sails.log.info('Initializing Quest job scheduler')
 
-      sails.after('hook:orm:loaded', async () => {
+      // Register cleanup before awaiting dependencies so failed lift also stops timers.
+      sails.on('lower', async () => {
+        sails.log.info('Stopping Quest jobs...')
+        await jobControl.stopJobs(null, context)
+      })
+
+      const initializeAfterOrm = async () => {
+        // The owned CLI child needs the app's hooks/context, but must not start
+        // another copy of its resident schedules, even if source config enables it.
+        if (isExecutionChild()) sails.config.quest.autoStart = false
+        const questConfig = {
+          ...sails.config.quest,
+          appPath:
+            sails.config.quest.appPath || sails.config.appPath || process.cwd()
+        }
+
         // Set up context with config
-        context.config = sails.config.quest
+        context.config = questConfig
         context.getNextRunTime = (job) =>
-          scheduler.getNextRunTime(job, sails.config.quest)
+          scheduler.getNextRunTime(job, questConfig, (assessment) => {
+            context.scheduleStates.set(job.name, {
+              ...context.scheduleStates.get(job.name),
+              ...assessment
+            })
+          })
         context.scheduleJob = (name) => jobControl.scheduleJob(name, context)
-        context.executeJob = (name, customInputs) => {
+        context.executeJob = (name, customInputs, trigger = 'manual') => {
           const job = jobs.get(name)
           if (!job) {
             // Try to run as a regular script without quest config
+            /** @type {QuestExecutableJob} */
             const minimalJob = {
               name,
               withoutOverlapping: false,
               inputs: {}
             }
-            return executor.executeJob(name, minimalJob, customInputs, context)
+            return executor.executeJob(name, minimalJob, customInputs, {
+              ...context,
+              trigger
+            })
           }
-          return executor.executeJob(name, job, customInputs, context)
+          return executor.executeJob(name, job, customInputs, {
+            ...context,
+            trigger
+          })
         }
 
         // Load jobs from scripts and config
-        await loader.loadJobs(sails.config.quest, jobs)
+        await loader.loadJobs(questConfig, jobs)
 
         // Start all jobs if autoStart is enabled
-        if (sails.config.quest.autoStart) {
+        if (questConfig.autoStart) {
           await jobControl.startJobs(null, context)
         }
 
         // Expose the Quest API
-        sails.quest = {
+        /** @type {QuestApi} */
+        const questApi = {
           // Core job control
           start: (jobNames) => jobControl.startJobs(jobNames, context),
           stop: (jobNames) => jobControl.stopJobs(jobNames, context),
@@ -92,12 +156,15 @@ module.exports = function defineQuestHook(sails) {
             jobControl.runJobs(jobNames, inputs, context),
           add: (jobDefs) => {
             const defs = Array.isArray(jobDefs) ? jobDefs : [jobDefs]
+            /** @type {string[]} */
             const added = []
             for (const def of defs) {
+              /** @type {QuestNamedJobDefinition} */
               const job = typeof def === 'string' ? { name: def } : def
-              loader.addJobDefinition(job, jobs, context.config)
+              loader.addJobDefinition(job, jobs, context.config || {})
+              context.scheduleStates.delete(job.name)
               added.push(job.name)
-              if (context.config.autoStart) {
+              if (context.config?.autoStart) {
                 jobControl.scheduleJob(job.name, context)
               }
             }
@@ -108,12 +175,17 @@ module.exports = function defineQuestHook(sails) {
             const removed = []
             for (const name of names) {
               if (loader.removeJob(name, jobs, timers)) {
+                context.dueTimes.delete(name)
+                context.scheduleStates.delete(name)
                 removed.push(name)
               }
             }
             return removed
           },
 
+          getRuntime: () => resident.runtimeInfo(context),
+          metadata: (name) => resident.metadata(context, name),
+
           // Job information
           jobs: Array.from(jobs.values()),
 
@@ -127,14 +199,19 @@ module.exports = function defineQuestHook(sails) {
           resume: (name) => jobControl.resumeJob(name, jobs)
         }
 
+        sails.quest = questApi
         sails.log.info(`Quest started with ${jobs.size} scheduled job(s)`)
-      })
+      }
 
-      // Graceful shutdown
-      sails.on('lower', async () => {
-        sails.log.info('Stopping Quest jobs...')
-        await jobControl.stopJobs(null, context)
+      // Sails waits for this Promise before marking Quest loaded. ORM initializes
+      // independently; after() also handles an ORM event that already occurred.
+      await new Promise((resolve, reject) => {
+        sails.after('hook:orm:loaded', () => {
+          initializeAfterOrm().then(resolve, reject)
+        })
       })
     }
   }
 }
+
+module.exports = defineQuestHook