sails-hook-quest 0.0.5 → 0.0.6

package/lib/core/job-control.js

@@ -25,8 +25,9 @@ const MAX_SAFE_TIMEOUT = 2_147_483_647 // 2^31 - 1, ~24.8 days
  * Schedule a job to run at its next scheduled time
  * @param {String} name - Job name
  * @param {QuestScheduleContext} [context] - Context with jobs, timers maps and helper functions
+ * @param {Date} [targetTime] - Original target for a long-delay intermediate timer
  */
-function scheduleJob(name, context = {}) {
+function scheduleJob(name, context = {}, targetTime) {
   const { jobs = new Map(), timers = new Map() } = context
   const getNextRunTime =
     /** @type {NonNullable<QuestScheduleContext['getNextRunTime']>} */ (
@@ -47,10 +48,33 @@ function scheduleJob(name, context = {}) {
   }
 
   // Clear any existing timer
-  stopJob(name, { timers })
+  stopJob(name, context)
 
   // Get the next run time
-  const nextRun = getNextRunTime(job)
+  const states = context.scheduleStates
+  const update = (registration) =>
+    states?.set(name, {
+      validation: 'not_checked',
+      validationErrors: [],
+      reason: null,
+      ...states.get(name),
+      registration
+    })
+  if (states && !targetTime)
+    states.set(name, {
+      validation: 'not_checked',
+      validationErrors: [],
+      reason: null,
+      lastAttemptAt: new Date().toISOString(),
+      registration: 'not_registered'
+    })
+  let nextRun
+  try {
+    nextRun = targetTime || getNextRunTime(job)
+  } catch (err) {
+    update('failed')
+    throw err
+  }
   if (!nextRun) {
     const sails = getGlobalSails()
     if (sails) {
@@ -61,11 +85,30 @@ function scheduleJob(name, context = {}) {
     return
   }
 
+  if (!Number.isFinite(nextRun.getTime())) {
+    states?.set(name, {
+      ...states.get(name),
+      registration: 'failed',
+      validation: 'invalid',
+      reason: null,
+      validationErrors: [
+        {
+          code: 'E_SCHEDULE_TARGET',
+          message: 'Schedule target must be a finite date.'
+        }
+      ]
+    })
+    return
+  }
   const delay = nextRun.getTime() - Date.now()
+  context.dueTimes?.set(name, nextRun)
 
   // If delay is negative (past time), run immediately
   if (delay <= 0) {
-    executeJob(name).catch((err) => {
+    timers.delete(name)
+    context.dueTimes?.delete(name)
+    update('consumed')
+    executeJob(name, undefined, 'scheduled').catch((err) => {
       const sails = getGlobalSails()
       if (sails) {
         sails.log.error(`Error running job "${name}":`, err)
@@ -83,10 +126,11 @@ function scheduleJob(name, context = {}) {
   // that rechecks when we're closer to the target time
   if (delay > MAX_SAFE_TIMEOUT) {
     const timer = setTimeout(() => {
-      scheduleJob(name, context)
+      scheduleJob(name, context, nextRun)
     }, MAX_SAFE_TIMEOUT)
 
     timers.set(name, timer)
+    update('registered')
 
     const sails = getGlobalSails()
     if (sails) {
@@ -99,7 +143,10 @@ function scheduleJob(name, context = {}) {
 
   // Set timer for the next execution
   const timer = setTimeout(() => {
-    executeJob(name).catch((err) => {
+    timers.delete(name)
+    context.dueTimes?.delete(name)
+    update('consumed')
+    executeJob(name, undefined, 'scheduled').catch((err) => {
       const sails = getGlobalSails()
       if (sails) {
         sails.log.error(`Error running job "${name}":`, err)
@@ -113,6 +160,7 @@ function scheduleJob(name, context = {}) {
   }, delay)
 
   timers.set(name, timer)
+  update('registered')
 
   const sails = getGlobalSails()
   if (sails) {
@@ -128,6 +176,19 @@ function scheduleJob(name, context = {}) {
 function stopJob(name, context = {}) {
   const { timers = new Map() } = context
 
+  context.dueTimes?.delete(name)
+  if (
+    context.scheduleStates &&
+    (context.scheduleStates.has(name) || context.jobs?.has(name))
+  )
+    context.scheduleStates.set(name, {
+      validation: 'not_checked',
+      validationErrors: [],
+      reason: null,
+      lastAttemptAt: null,
+      ...context.scheduleStates.get(name),
+      registration: 'stopped'
+    })
   const timer = timers.get(name)
   if (timer) {
     clearTimeout(timer)
@@ -180,7 +241,7 @@ function stopJobs(jobNames, context = {}) {
       : [jobNames]
 
   for (const name of names) {
-    stopJob(name, { timers })
+    stopJob(name, context)
   }
 }
 
@@ -203,7 +264,7 @@ async function runJobs(jobNames, inputs, context = {}) {
       ? jobNames
       : [jobNames]
 
-  const promises = names.map((name) => executeJob(name, inputs))
+  const promises = names.map((name) => executeJob(name, inputs, 'manual'))
   return Promise.all(promises)
 }
 

package/lib/core/loader.js

@@ -75,7 +75,7 @@ async function loadJobs(config, jobs = new Map()) {
     for (const jobDef of config.jobs) {
       // Handle string shorthand (just job name)
       /** @type {QuestJobDefinition} */
-      const job = typeof jobDef === 'string' ? { name: jobDef } : jobDef
+      const job = typeof jobDef === 'string' ? { name: jobDef } : { ...jobDef }
       const jobName = job.name
 
       // Check for duplicate job names in config
@@ -89,11 +89,13 @@ async function loadJobs(config, jobs = new Map()) {
       }
 
       // Try to get script inputs if the script exists
-      const scriptDef = jobName ? scripts[jobName] : undefined
+      const scriptDef = jobName ? scripts[job.script || jobName] : undefined
       if (scriptDef && !job.scriptInputs) {
         job.scriptInputs = extractScriptInputDefaults(scriptDef.inputs)
       }
 
+      job.script = job.script || jobName
+      job.inputSchema = scriptDef ? scriptDef.inputs || {} : undefined
       addJobDefinition(job, jobs, config)
     }
   }
@@ -122,7 +124,9 @@ async function loadJobs(config, jobs = new Map()) {
       withoutOverlapping: existingJob?.withoutOverlapping,
       inputs: { ...(existingJob?.inputs || {}), ...(questConfig.inputs || {}) },
       ...questConfig,
-      scriptInputs
+      scriptInputs,
+      script: scriptName,
+      inputSchema: scriptDef.inputs || {}
     }
 
     addJobDefinition(jobDef, jobs, config)
@@ -152,6 +156,8 @@ function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
   /** @type {QuestJob} */
   const job = {
     name,
+    script: jobDef.script || name,
+    inputSchema: jobDef.inputSchema,
     friendlyName: jobDef.friendlyName || name,
     description: jobDef.description,
 

package/lib/core/result.js

@@ -0,0 +1,91 @@
+// @ts-check
+
+const DEFAULT_RESULT_BYTES = 64 * 1024
+const MAX_RESULT_BYTES = 1024 * 1024
+
+/** @param {number} [value] */
+function byteLimit(value) {
+  return Number.isFinite(value) && value > 0
+    ? Math.min(MAX_RESULT_BYTES, Math.floor(value))
+    : DEFAULT_RESULT_BYTES
+}
+
+/**
+ * Encode plain JSON without executing getters/toJSON or allocating an unbounded
+ * intermediate JSON string. Depth/node limits bound even tiny nested values.
+ * @param {any} value
+ * @param {number} [requestedBytes]
+ * @returns {{status: string, value?: any, json?: string, exit?: string}}
+ */
+function encodeResult(value, requestedBytes) {
+  if (value === undefined) return { status: 'undefined' }
+  const limit = byteLimit(requestedBytes)
+  const parts = []
+  const ancestors = new Set()
+  let bytes = 0
+  let nodes = 0
+  function append(text) {
+    bytes += Buffer.byteLength(text)
+    if (bytes > limit) throw new RangeError('too_large')
+    parts.push(text)
+  }
+  function visit(item, depth) {
+    if (++nodes > 10000 || depth > 64) throw new RangeError('too_large')
+    if (item === null) return append('null')
+    if (typeof item === 'boolean') return append(String(item))
+    if (typeof item === 'number' && Number.isFinite(item))
+      return append(String(item))
+    if (typeof item === 'string') {
+      if (
+        item.length > limit - bytes ||
+        Buffer.byteLength(item) > limit - bytes
+      )
+        throw new RangeError('too_large')
+      return append(JSON.stringify(item))
+    }
+    if (typeof item !== 'object') throw new TypeError('non_json')
+    if (ancestors.has(item)) throw new TypeError('circular')
+    const array = Array.isArray(item)
+    if (
+      !array &&
+      Object.getPrototypeOf(item) !== Object.prototype &&
+      Object.getPrototypeOf(item) !== null
+    ) {
+      throw new TypeError('non_plain_object')
+    }
+    ancestors.add(item)
+    append(array ? '[' : '{')
+    const keys = array ? null : Object.keys(item)
+    const count = array ? item.length : keys.length
+    if (count > 10000) throw new RangeError('too_large')
+    for (let i = 0; i < count; i++) {
+      if (i) append(',')
+      const key = array ? String(i) : keys[i]
+      if (!array) {
+        if (
+          key.length > limit - bytes ||
+          Buffer.byteLength(key) > limit - bytes
+        )
+          throw new RangeError('too_large')
+        append(JSON.stringify(key) + ':')
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(item, key)
+      if (!descriptor || !('value' in descriptor))
+        throw new TypeError('non_json_property')
+      visit(descriptor.value, depth + 1)
+    }
+    append(array ? ']' : '}')
+    ancestors.delete(item)
+  }
+  try {
+    visit(value, 0)
+    const json = parts.join('')
+    return { status: 'available', value: JSON.parse(json), json }
+  } catch (error) {
+    return {
+      status: error instanceof RangeError ? 'too_large' : 'serialization_error'
+    }
+  }
+}
+
+module.exports = { encodeResult, byteLimit }

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

@@ -19,72 +19,110 @@ const { getGlobalSails } = require('./global-sails')
  * Parse various schedule formats and return next run time
  * @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) {
       const sails = getGlobalSails()
-      if (sails) {
-        sails.log.error(
-          `Invalid cron expression for job "${job.name}": ${job.cron}`,
-          err instanceof Error ? err.message : err
-        )
-      }
-      return null
+      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
-
-    const sails = getGlobalSails()
-    if (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
 }
 
 /**
@@ -207,6 +245,7 @@ function convertShorthand(str) {
 
 module.exports = {
   getNextRunTime,
+  effectiveTimezone,
   parseInterval,
   parseTimeout,
   convertShorthand