sails-hook-quest 0.0.3 → 0.0.5

package/README.md

@@ -79,6 +79,9 @@ module.exports.quest = {
   // Run jobs in console environment (minimal Sails lift)
   environment: 'console',
 
+  // Retain the final 64 KiB of child output when a job fails
+  diagnosticTailBytes: 64 * 1024,
+
   // Define additional jobs in config
   jobs: [
     {
@@ -215,10 +218,20 @@ Each event includes:
   inputs: { /* job inputs */ },
   timestamp: Date,
   duration: 1234,  // milliseconds (complete/error only)
-  error: { }       // error details (error event only)
+  error: {
+    message: 'Job "job-name" exited with code 1',
+    code: 1,
+    stack: 'Error: Job "job-name" exited with code 1\\n...',
+    diagnostic: 'The final bounded section of the child process output'
+  }
 }
 ```
 
+Job output still streams live to the parent process. On failure, Quest also
+includes a bounded diagnostic tail and a parent stack in the error event so
+observability tools can preserve the useful failure context without buffering
+the complete job log.
+
 ## Console Environment
 
 Quest can run jobs in a minimal 'console' environment that skips unnecessary hooks for better performance:

package/jsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "maxNodeModuleJsDepth": 0,
+    "strict": false,
+    "skipLibCheck": true
+  },
+  "include": ["lib/**/*.js", "typecheck/**/*.js"],
+  "exclude": ["node_modules"]
+}

package/lib/core/executor.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * core/executor.js
  *
@@ -7,21 +9,30 @@
 const { spawn } = require('child_process')
 const fs = require('fs')
 const path = require('path')
+const { getGlobalSails } = require('./global-sails')
+
+const DEFAULT_DIAGNOSTIC_TAIL_BYTES = 64 * 1024
+
+/** @typedef {import('../types').AnyRecord} AnyRecord */
+/** @typedef {import('../types').QuestExecutableJob} QuestExecutableJob */
+/** @typedef {import('../types').QuestExecutionResult} QuestExecutionResult */
+/** @typedef {import('../types').QuestExecutorContext} QuestExecutorContext */
 
 /**
  * Execute a job via `sails run`
  * @param {String} name - Job name
- * @param {Object} job - Job configuration
- * @param {Object} customInputs - Custom input values
- * @param {Object} context - Execution context with running map, config, etc
- * @returns {Promise} Resolves when job completes
+ * @param {QuestExecutableJob} job - Job configuration
+ * @param {AnyRecord} [customInputs] - Custom input values
+ * @param {QuestExecutorContext} [context] - Execution context with running map, config, etc
+ * @returns {Promise<QuestExecutionResult>} Resolves when job completes
  */
 async function executeJob(name, job, customInputs = {}, context = {}) {
   const { running = new Map(), config = {} } = context
 
   // Check if job is already running (and overlapping is disabled)
   if (job.withoutOverlapping && running.has(name)) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn(`Job "${name}" is already running, skipping...`)
     }
     return { skipped: true, reason: 'already_running' }
@@ -29,23 +40,29 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
 
   // Don't run if paused
   if (job.paused) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.verbose(`Job "${name}" is paused, skipping...`)
     }
     return { skipped: true, reason: 'paused' }
   }
 
-  if (global.sails) {
+  const sails = getGlobalSails()
+  if (sails) {
     sails.log.info(`Running job: ${name}`)
   }
 
   running.set(name, Date.now())
 
   // Merge inputs with priority: jobInputs < scriptInputs < customInputs
-  const inputs = { ...job.inputs, ...job.scriptInputs, ...customInputs }
+  const inputs = {
+    ...(job.inputs || {}),
+    ...(job.scriptInputs || {}),
+    ...customInputs
+  }
 
   // Emit job start event
-  if (global.sails) {
+  if (sails) {
     sails.emit('quest:job:start', {
       name,
       inputs,
@@ -74,12 +91,12 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
       const error = new Error(
         `Job "${name}" not found. Please check that the script exists at ${scriptsDir}/${name}.js`
       )
-      if (global.sails) {
+      if (sails) {
         sails.log.error(error.message)
         sails.emit('quest:job:error', {
           name,
           inputs,
-          error: { message: error.message },
+          error: { message: error.message, stack: error.stack },
           duration: 0,
           timestamp: new Date()
         })
@@ -87,19 +104,37 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
       return reject(error)
     }
 
+    const diagnosticTail = createDiagnosticTail(config.diagnosticTailBytes)
     const child = spawn(sailsPath, args, {
       cwd,
       env,
-      stdio: 'inherit'
+      stdio: ['inherit', 'pipe', 'pipe']
     })
 
-    child.on('exit', (code) => {
-      const startTime = running.get(name)
+    teeChildOutput(
+      child.stdout,
+      context.stdout || process.stdout,
+      diagnosticTail
+    )
+    teeChildOutput(
+      child.stderr,
+      context.stderr || process.stderr,
+      diagnosticTail
+    )
+
+    let settled = false
+
+    child.on('close', (code) => {
+      if (settled) {
+        return
+      }
+      settled = true
+      const startTime = /** @type {number} */ (running.get(name))
       const duration = Date.now() - startTime
       running.delete(name)
 
       if (code === 0) {
-        if (global.sails) {
+        if (sails) {
           sails.log.info(`Job "${name}" completed successfully`)
 
           // Emit success event
@@ -115,7 +150,7 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
       } else {
         const error = new Error(`Job "${name}" exited with code ${code}`)
 
-        if (global.sails) {
+        if (sails) {
           sails.log.error(error)
 
           // Emit error event
@@ -124,7 +159,9 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
             inputs,
             error: {
               message: error.message,
-              code
+              code,
+              stack: error.stack,
+              diagnostic: diagnosticTail.value()
             },
             duration,
             timestamp: new Date()
@@ -136,11 +173,15 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
     })
 
     child.on('error', (err) => {
+      if (settled) {
+        return
+      }
+      settled = true
       const startTime = running.get(name) || Date.now()
       const duration = Date.now() - startTime
       running.delete(name)
 
-      if (global.sails) {
+      if (sails) {
         sails.log.error(`Job "${name}" failed to start:`, err)
 
         // Emit error event
@@ -149,7 +190,8 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
           inputs,
           error: {
             message: err.message,
-            stack: err.stack
+            stack: err.stack,
+            diagnostic: diagnosticTail.value()
           },
           duration,
           timestamp: new Date()
@@ -161,11 +203,57 @@ async function executeJob(name, job, customInputs = {}, context = {}) {
   })
 }
 
+/**
+ * Retain only the end of child output so a failed job can explain itself
+ * without buffering an unbounded process log.
+ *
+ * @param {number} [requestedMaxBytes]
+ */
+function createDiagnosticTail(requestedMaxBytes) {
+  const maxBytes =
+    Number.isFinite(requestedMaxBytes) && requestedMaxBytes > 0
+      ? Math.floor(requestedMaxBytes)
+      : DEFAULT_DIAGNOSTIC_TAIL_BYTES
+  let buffer = Buffer.alloc(0)
+
+  return {
+    /** @param {Buffer|string} chunk */
+    append(chunk) {
+      const incoming = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      buffer = Buffer.concat([buffer, incoming])
+      if (buffer.length > maxBytes) {
+        buffer = buffer.subarray(buffer.length - maxBytes)
+      }
+    },
+    value() {
+      return buffer.toString('utf8').trim()
+    }
+  }
+}
+
+/**
+ * Mirror child output to the parent while retaining a bounded diagnostic tail.
+ *
+ * @param {NodeJS.ReadableStream|null} source
+ * @param {NodeJS.WritableStream} destination
+ * @param {ReturnType<typeof createDiagnosticTail>} diagnosticTail
+ */
+function teeChildOutput(source, destination, diagnosticTail) {
+  if (!source) {
+    return
+  }
+
+  source.on('data', (chunk) => {
+    diagnosticTail.append(chunk)
+    destination.write(chunk)
+  })
+}
+
 /**
  * Build command arguments for sails run
  * @param {String} scriptName - Name of the script
- * @param {Object} inputs - Input values
- * @returns {Array} Command arguments
+ * @param {AnyRecord} [inputs] - Input values
+ * @returns {string[]} Command arguments
  */
 function buildCommandArgs(scriptName, inputs = {}) {
   const args = ['run', scriptName]
@@ -186,5 +274,6 @@ function buildCommandArgs(scriptName, inputs = {}) {
 
 module.exports = {
   executeJob,
-  buildCommandArgs
+  buildCommandArgs,
+  createDiagnosticTail
 }

package/lib/core/global-sails.js

@@ -0,0 +1,16 @@
+// @ts-check
+
+/** @typedef {import('../types').QuestSailsApp} QuestSailsApp */
+
+/**
+ * Resolve the ambient Sails app when core modules run outside the hook factory.
+ *
+ * @returns {QuestSailsApp | undefined}
+ */
+function getGlobalSails() {
+  return /** @type {{ sails?: QuestSailsApp }} */ (global).sails
+}
+
+module.exports = {
+  getGlobalSails
+}

package/lib/core/job-control.js

@@ -1,25 +1,46 @@
+// @ts-check
+
 /**
  * core/job-control.js
  *
  * Functions for controlling job lifecycle (start, stop, pause, resume)
  */
 
+const { getGlobalSails } = require('./global-sails')
+
+/** @typedef {import('../types').AnyRecord} AnyRecord */
+/** @typedef {import('../types').QuestExecutionResult} QuestExecutionResult */
+/** @typedef {import('../types').QuestJobNameInput} QuestJobNameInput */
+/** @typedef {import('../types').QuestJobsMap} QuestJobsMap */
+/** @typedef {import('../types').QuestRunContext} QuestRunContext */
+/** @typedef {import('../types').QuestScheduleContext} QuestScheduleContext */
+/** @typedef {import('../types').QuestStartContext} QuestStartContext */
+/** @typedef {import('../types').QuestStopContext} QuestStopContext */
+
+// setTimeout uses a 32-bit signed integer internally.
+// Delays larger than this overflow and fire immediately (~1ms), causing infinite loops.
+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 {Object} context - Context with jobs, timers maps and helper functions
+ * @param {QuestScheduleContext} [context] - Context with jobs, timers maps and helper functions
  */
 function scheduleJob(name, context = {}) {
-  const {
-    jobs = new Map(),
-    timers = new Map(),
-    getNextRunTime,
-    executeJob
-  } = context
+  const { jobs = new Map(), timers = new Map() } = context
+  const getNextRunTime =
+    /** @type {NonNullable<QuestScheduleContext['getNextRunTime']>} */ (
+      context.getNextRunTime
+    )
+  const executeJob =
+    /** @type {NonNullable<QuestScheduleContext['executeJob']>} */ (
+      context.executeJob
+    )
 
   const job = jobs.get(name)
   if (!job) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn(`Job "${name}" not found in jobs Map`)
     }
     return
@@ -31,7 +52,8 @@ function scheduleJob(name, context = {}) {
   // Get the next run time
   const nextRun = getNextRunTime(job)
   if (!nextRun) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn(
         `Job "${name}" has no valid schedule (interval: ${job.interval}, cron: ${job.cron}, timeout: ${job.timeout})`
       )
@@ -44,7 +66,8 @@ function scheduleJob(name, context = {}) {
   // If delay is negative (past time), run immediately
   if (delay <= 0) {
     executeJob(name).catch((err) => {
-      if (global.sails) {
+      const sails = getGlobalSails()
+      if (sails) {
         sails.log.error(`Error running job "${name}":`, err)
       }
     })
@@ -56,10 +79,29 @@ function scheduleJob(name, context = {}) {
     return
   }
 
+  // If delay exceeds the 32-bit setTimeout max, set an intermediate timer
+  // that rechecks when we're closer to the target time
+  if (delay > MAX_SAFE_TIMEOUT) {
+    const timer = setTimeout(() => {
+      scheduleJob(name, context)
+    }, MAX_SAFE_TIMEOUT)
+
+    timers.set(name, timer)
+
+    const sails = getGlobalSails()
+    if (sails) {
+      sails.log.verbose(
+        `Job "${name}" scheduled for ${nextRun.toISOString()} (delay exceeds 24.8d, re-checking later)`
+      )
+    }
+    return
+  }
+
   // Set timer for the next execution
   const timer = setTimeout(() => {
     executeJob(name).catch((err) => {
-      if (global.sails) {
+      const sails = getGlobalSails()
+      if (sails) {
         sails.log.error(`Error running job "${name}":`, err)
       }
     })
@@ -72,7 +114,8 @@ function scheduleJob(name, context = {}) {
 
   timers.set(name, timer)
 
-  if (global.sails) {
+  const sails = getGlobalSails()
+  if (sails) {
     sails.log.verbose(`Job "${name}" scheduled for ${nextRun.toISOString()}`)
   }
 }
@@ -80,7 +123,7 @@ function scheduleJob(name, context = {}) {
 /**
  * Stop a single job
  * @param {String} name - Job name
- * @param {Object} context - Context with timers map
+ * @param {QuestStopContext} [context] - Context with timers map
  */
 function stopJob(name, context = {}) {
   const { timers = new Map() } = context
@@ -90,7 +133,8 @@ function stopJob(name, context = {}) {
     clearTimeout(timer)
     clearInterval(timer)
     timers.delete(name)
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.verbose(`Job "${name}" stopped`)
     }
   }
@@ -98,11 +142,16 @@ function stopJob(name, context = {}) {
 
 /**
  * Start scheduling jobs
- * @param {String|Array} jobNames - Job names to start (optional)
- * @param {Object} context - Context with jobs map and scheduleJob function
+ * @param {QuestJobNameInput} jobNames - Job names to start (optional)
+ * @param {QuestStartContext} [context] - Context with jobs map and scheduleJob function
+ * @returns {Promise<void>}
  */
 async function startJobs(jobNames, context = {}) {
-  const { jobs = new Map(), scheduleJob } = context
+  const { jobs = new Map() } = context
+  const scheduleJob =
+    /** @type {NonNullable<QuestStartContext['scheduleJob']>} */ (
+      context.scheduleJob
+    )
 
   const names = !jobNames
     ? Array.from(jobs.keys())
@@ -117,8 +166,9 @@ async function startJobs(jobNames, context = {}) {
 
 /**
  * Stop scheduling jobs
- * @param {String|Array} jobNames - Job names to stop (optional)
- * @param {Object} context - Context with jobs and timers maps
+ * @param {QuestJobNameInput} jobNames - Job names to stop (optional)
+ * @param {QuestStopContext} [context] - Context with jobs and timers maps
+ * @returns {void}
  */
 function stopJobs(jobNames, context = {}) {
   const { jobs = new Map(), timers = new Map() } = context
@@ -136,12 +186,16 @@ function stopJobs(jobNames, context = {}) {
 
 /**
  * Run jobs immediately
- * @param {String|Array} jobNames - Job names to run
- * @param {Object} inputs - Custom inputs
- * @param {Object} context - Context with executeJob function
+ * @param {QuestJobNameInput} jobNames - Job names to run
+ * @param {AnyRecord} [inputs] - Custom inputs
+ * @param {QuestRunContext} [context] - Context with executeJob function
+ * @returns {Promise<QuestExecutionResult[]>}
  */
 async function runJobs(jobNames, inputs, context = {}) {
-  const { jobs = new Map(), executeJob } = context
+  const { jobs = new Map() } = context
+  const executeJob = /** @type {NonNullable<QuestRunContext['executeJob']>} */ (
+    context.executeJob
+  )
 
   const names = !jobNames
     ? Array.from(jobs.keys())
@@ -156,7 +210,8 @@ async function runJobs(jobNames, inputs, context = {}) {
 /**
  * Pause a job
  * @param {String} name - Job name
- * @param {Map} jobs - Jobs map
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @returns {boolean}
  */
 function pauseJob(name, jobs = new Map()) {
   const job = jobs.get(name)
@@ -170,7 +225,8 @@ function pauseJob(name, jobs = new Map()) {
 /**
  * Resume a job
  * @param {String} name - Job name
- * @param {Map} jobs - Jobs map
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @returns {boolean}
  */
 function resumeJob(name, jobs = new Map()) {
   const job = jobs.get(name)

package/lib/core/loader.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * core/loader.js
  *
@@ -6,13 +8,24 @@
 
 const path = require('path')
 const includeAll = require('include-all')
+const { getGlobalSails } = require('./global-sails')
+
+/** @typedef {import('../types').AnyRecord} AnyRecord */
+/** @typedef {import('../types').QuestConfig} QuestConfig */
+/** @typedef {import('../types').QuestJob} QuestJob */
+/** @typedef {import('../types').QuestJobDefinition} QuestJobDefinition */
+/** @typedef {import('../types').QuestJobsMap} QuestJobsMap */
+/** @typedef {import('../types').QuestMachineInputs} QuestMachineInputs */
+/** @typedef {import('../types').QuestScriptDefinition} QuestScriptDefinition */
+/** @typedef {import('../types').QuestTimersMap} QuestTimersMap */
 
 /**
  * Extract default values from a script's inputs schema
- * @param {Object} inputs - Script's inputs definition (Sails machine format)
- * @returns {Object} Object with input names and their defaultsTo values
+ * @param {QuestMachineInputs | null | undefined} inputs - Script's inputs definition (Sails machine format)
+ * @returns {AnyRecord} Object with input names and their defaultsTo values
  */
 function extractScriptInputDefaults(inputs) {
+  /** @type {AnyRecord} */
   const defaults = {}
   if (!inputs || typeof inputs !== 'object') return defaults
 
@@ -26,9 +39,9 @@ function extractScriptInputDefaults(inputs) {
 
 /**
  * Load jobs from scripts directory and config
- * @param {Object} config - Quest configuration
- * @param {Map} jobs - Jobs map to populate
- * @returns {Promise<Map>} Populated jobs map
+ * @param {QuestConfig} config - Quest configuration
+ * @param {QuestJobsMap} [jobs] - Jobs map to populate
+ * @returns {Promise<QuestJobsMap>} Populated jobs map
  */
 async function loadJobs(config, jobs = new Map()) {
   // First, load scripts from the scripts directory
@@ -36,17 +49,21 @@ async function loadJobs(config, jobs = new Map()) {
   const appPath = config.appPath || process.cwd()
   const fullPath = path.resolve(appPath, scriptsDir)
 
+  /** @type {Record<string, QuestScriptDefinition>} */
   let scripts = {}
 
   try {
-    scripts = includeAll({
-      dirname: fullPath,
-      filter: /(.+)\.js$/,
-      excludeDirs: /^\.(git|svn)$/,
-      flatten: true
-    })
+    scripts = /** @type {Record<string, QuestScriptDefinition>} */ (
+      includeAll({
+        dirname: fullPath,
+        filter: /(.+)\.js$/,
+        excludeDirs: /^\.(git|svn)$/,
+        flatten: true
+      })
+    )
   } catch (e) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.verbose('No scripts directory found, skipping script jobs')
     }
   }
@@ -57,18 +74,22 @@ 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 jobName = job.name
 
       // Check for duplicate job names in config
-      if (configJobNames.has(job.name)) {
+      if (jobName && configJobNames.has(jobName)) {
         throw new Error(
-          `Duplicate job name "${job.name}" in config/quest.js. Each job must have a unique name.`
+          `Duplicate job name "${jobName}" in config/quest.js. Each job must have a unique name.`
         )
       }
-      configJobNames.add(job.name)
+      if (jobName) {
+        configJobNames.add(jobName)
+      }
 
       // Try to get script inputs if the script exists
-      const scriptDef = scripts[job.name]
+      const scriptDef = jobName ? scripts[jobName] : undefined
       if (scriptDef && !job.scriptInputs) {
         job.scriptInputs = extractScriptInputDefaults(scriptDef.inputs)
       }
@@ -92,13 +113,14 @@ async function loadJobs(config, jobs = new Map()) {
     const existingJob = jobs.get(jobName)
 
     // Merge: config as base, script quest config takes priority
+    /** @type {QuestJobDefinition} */
     const jobDef = {
       name: jobName,
       friendlyName: scriptDef.friendlyName,
       description: scriptDef.description,
       // Preserve config's withoutOverlapping if script doesn't specify
       withoutOverlapping: existingJob?.withoutOverlapping,
-      inputs: { ...existingJob?.inputs, ...questConfig.inputs },
+      inputs: { ...(existingJob?.inputs || {}), ...(questConfig.inputs || {}) },
       ...questConfig,
       scriptInputs
     }
@@ -111,21 +133,23 @@ async function loadJobs(config, jobs = new Map()) {
 
 /**
  * Add a job definition to the jobs Map
- * @param {Object} jobDef - Job definition
- * @param {Map} jobs - Jobs map
- * @param {Object} config - Quest configuration
- * @returns {Object} Normalized job
+ * @param {QuestJobDefinition} jobDef - Job definition
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @param {QuestConfig} [config] - Quest configuration
+ * @returns {QuestJob | null} Normalized job
  */
 function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
   const name = jobDef.name
   if (!name) {
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.warn('Job definition missing name, skipping:', jobDef)
     }
     return null
   }
 
   // Parse and normalize the job definition
+  /** @type {QuestJob} */
   const job = {
     name,
     friendlyName: jobDef.friendlyName || name,
@@ -151,7 +175,8 @@ function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
 
   jobs.set(name, job)
 
-  if (global.sails) {
+  const sails = getGlobalSails()
+  if (sails) {
     const schedule = {}
     if (job.interval !== undefined) schedule.interval = job.interval
     if (job.cron !== undefined) schedule.cron = job.cron
@@ -165,8 +190,8 @@ function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
 /**
  * Remove a job from the jobs map
  * @param {String} name - Job name
- * @param {Map} jobs - Jobs map
- * @param {Map} timers - Timers map
+ * @param {QuestJobsMap} [jobs] - Jobs map
+ * @param {QuestTimersMap} [timers] - Timers map
  * @returns {Boolean} Success
  */
 function removeJob(name, jobs = new Map(), timers = new Map()) {
@@ -181,7 +206,8 @@ function removeJob(name, jobs = new Map(), timers = new Map()) {
   // Remove from jobs map
   const existed = jobs.delete(name)
 
-  if (existed && global.sails) {
+  const sails = getGlobalSails()
+  if (existed && sails) {
     sails.log.verbose(`Job "${name}" removed`)
   }
 

package/lib/core/scheduler.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * core/scheduler.js
  *
@@ -7,11 +9,16 @@
 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
  * @returns {Date|null} Next run time or null if invalid
  */
 function getNextRunTime(job, config = {}) {
@@ -36,10 +43,11 @@ function getNextRunTime(job, config = {}) {
       const interval = CronExpressionParser.parse(job.cron, options)
       return interval.next().toDate()
     } catch (err) {
-      if (global.sails) {
+      const sails = getGlobalSails()
+      if (sails) {
         sails.log.error(
           `Invalid cron expression for job "${job.name}": ${job.cron}`,
-          err.message
+          err instanceof Error ? err.message : err
         )
       }
       return null
@@ -51,7 +59,8 @@ function getNextRunTime(job, config = {}) {
     const nextTime = parseInterval(job.interval, now)
     if (nextTime) return nextTime
 
-    if (global.sails) {
+    const sails = getGlobalSails()
+    if (sails) {
       sails.log.error(`Invalid interval for job "${job.name}": ${job.interval}`)
     }
     return null
@@ -95,6 +104,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 +148,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
  */

package/lib/index.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * sails-hook-quest
  *
@@ -10,12 +12,34 @@ const executor = require('./core/executor')
 const loader = require('./core/loader')
 const jobControl = require('./core/job-control')
 
-module.exports = function defineQuestHook(sails) {
+/** @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 */
+
+/**
+ * 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,
@@ -47,6 +71,9 @@ module.exports = function defineQuestHook(sails) {
         // Directory containing job scripts
         scriptsDir: 'scripts',
 
+        // Maximum child output retained on failure (live output remains unbounded)
+        diagnosticTailBytes: 64 * 1024,
+
         // Jobs defined in config
         jobs: []
       }
@@ -56,15 +83,18 @@ module.exports = function defineQuestHook(sails) {
       sails.log.info('Initializing Quest job scheduler')
 
       sails.after('hook:orm:loaded', async () => {
+        const questConfig = sails.config.quest
+
         // 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)
         context.scheduleJob = (name) => jobControl.scheduleJob(name, context)
         context.executeJob = (name, customInputs) => {
           const job = jobs.get(name)
           if (!job) {
             // Try to run as a regular script without quest config
+            /** @type {QuestExecutableJob} */
             const minimalJob = {
               name,
               withoutOverlapping: false,
@@ -76,15 +106,16 @@ module.exports = function defineQuestHook(sails) {
         }
 
         // 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 +123,14 @@ 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 || {})
               added.push(job.name)
-              if (context.config.autoStart) {
+              if (context.config?.autoStart) {
                 jobControl.scheduleJob(job.name, context)
               }
             }
@@ -127,6 +160,7 @@ 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)`)
       })
 
@@ -138,3 +172,5 @@ module.exports = function defineQuestHook(sails) {
     }
   }
 }
+
+module.exports = defineQuestHook

package/lib/types.js

@@ -0,0 +1,231 @@
+/**
+ * Shared TypeScript-consumable JSDoc typedefs for Quest's public API.
+ *
+ * These comments are intentionally colocated with the JavaScript source so JSDoc
+ * stays the source of truth for editor autocomplete and local type checks.
+ *
+ * @typedef {Record<string, any>} AnyRecord
+ *
+ * @typedef {string | number | boolean | null} JsonPrimitive
+ *
+ * @typedef {JsonPrimitive | any[] | AnyRecord} JsonValue
+ *
+ * @typedef {string | number} QuestInterval
+ *
+ * @typedef {string | number | false} QuestTimeout
+ *
+ * @typedef {string | number | Date} QuestDateInput
+ *
+ * @typedef {Record<string, any>} QuestCronOptions
+ *
+ * @typedef {{
+ *   defaultsTo?: any,
+ *   type?: string,
+ *   description?: string,
+ *   required?: boolean,
+ *   allowNull?: boolean,
+ *   [key: string]: any,
+ * }} QuestMachineInputDefinition
+ *
+ * @typedef {Record<string, QuestMachineInputDefinition>} QuestMachineInputs
+ *
+ * @typedef {{
+ *   name?: string,
+ *   friendlyName?: string,
+ *   description?: string,
+ *   interval?: QuestInterval,
+ *   timeout?: QuestTimeout,
+ *   cron?: string,
+ *   cronOptions?: QuestCronOptions,
+ *   date?: QuestDateInput,
+ *   timezone?: string,
+ *   inputs?: AnyRecord,
+ *   scriptInputs?: AnyRecord,
+ *   withoutOverlapping?: boolean,
+ *   paused?: boolean,
+ *   [key: string]: any,
+ * }} QuestJobDefinition
+ *
+ * @typedef {QuestJobDefinition & { name: string }} QuestNamedJobDefinition
+ *
+ * @typedef {string | QuestNamedJobDefinition} QuestJobDefinitionInput
+ *
+ * @typedef {{
+ *   name: string,
+ *   friendlyName: string,
+ *   description?: string,
+ *   interval?: QuestInterval,
+ *   timeout?: QuestTimeout,
+ *   cron?: string,
+ *   cronOptions?: QuestCronOptions,
+ *   date?: QuestDateInput,
+ *   timezone?: string,
+ *   inputs: AnyRecord,
+ *   scriptInputs: AnyRecord,
+ *   paused: boolean,
+ *   withoutOverlapping: boolean,
+ * }} QuestJob
+ *
+ * @typedef {{
+ *   name: string,
+ *   inputs?: AnyRecord,
+ *   scriptInputs?: AnyRecord,
+ *   paused?: boolean,
+ *   withoutOverlapping?: boolean,
+ * }} QuestExecutableJob
+ *
+ * @typedef {{
+ *   friendlyName?: string,
+ *   description?: string,
+ *   quest?: QuestJobDefinition,
+ *   inputs?: QuestMachineInputs,
+ *   fn?: Function,
+ *   [key: string]: any,
+ * }} QuestScriptDefinition
+ *
+ * @typedef {string | string[] | null | undefined} QuestJobNameInput
+ *
+ * @typedef {{
+ *   autoStart?: boolean,
+ *   timezone?: string,
+ *   withoutOverlapping?: boolean,
+ *   sailsPath?: string,
+ *   environment?: string,
+ *   scriptsDir?: string,
+ *   appPath?: string,
+ *   diagnosticTailBytes?: number,
+ *   jobs?: QuestJobDefinitionInput[],
+ *   [key: string]: any,
+ * }} QuestConfig
+ *
+ * @typedef {{
+ *   skipped: true,
+ *   reason: 'already_running' | 'paused',
+ * }} QuestSkippedResult
+ *
+ * @typedef {{
+ *   success: true,
+ *   duration: number,
+ * }} QuestSuccessResult
+ *
+ * @typedef {QuestSkippedResult | QuestSuccessResult} QuestExecutionResult
+ *
+ * @typedef {{
+ *   name: string,
+ *   inputs: AnyRecord,
+ *   timestamp: Date,
+ * }} QuestJobStartEvent
+ *
+ * @typedef {{
+ *   name: string,
+ *   inputs: AnyRecord,
+ *   duration: number,
+ *   timestamp: Date,
+ * }} QuestJobCompleteEvent
+ *
+ * @typedef {{
+ *   message: string,
+ *   code?: number | null,
+ *   stack?: string,
+ *   diagnostic?: string,
+ * }} QuestJobErrorDetails
+ *
+ * @typedef {{
+ *   name: string,
+ *   inputs: AnyRecord,
+ *   error: QuestJobErrorDetails,
+ *   duration: number,
+ *   timestamp: Date,
+ * }} QuestJobErrorEvent
+ *
+ * @typedef {{
+ *   start(jobNames?: QuestJobNameInput): Promise<void>,
+ *   stop(jobNames?: QuestJobNameInput): void,
+ *   run(jobNames?: QuestJobNameInput, inputs?: AnyRecord): Promise<QuestExecutionResult[]>,
+ *   add(jobDefs: QuestJobDefinitionInput | QuestJobDefinitionInput[]): string[],
+ *   remove(jobNames: QuestJobNameInput): string[],
+ *   jobs: QuestJob[],
+ *   list(): QuestJob[],
+ *   get(name: string): QuestJob | undefined,
+ *   isRunning(name: string): boolean,
+ *   pause(name: string): boolean,
+ *   resume(name: string): boolean,
+ * }} QuestApi
+ *
+ * @typedef {Map<string, QuestJob>} QuestJobsMap
+ *
+ * @typedef {Map<string, ReturnType<typeof setTimeout>>} QuestTimersMap
+ *
+ * @typedef {Map<string, number>} QuestRunningMap
+ *
+ * @typedef {{
+ *   jobs: QuestJobsMap,
+ *   timers: QuestTimersMap,
+ *   running: QuestRunningMap,
+ *   config: QuestConfig | null,
+ *   scheduleJob: ((name: string) => void) | null,
+ *   executeJob: ((name: string, customInputs?: AnyRecord) => Promise<QuestExecutionResult>) | null,
+ *   getNextRunTime: ((job: QuestJob) => Date | null) | null,
+ * }} QuestContext
+ *
+ * @typedef {{
+ *   jobs?: QuestJobsMap,
+ *   timers?: QuestTimersMap,
+ *   getNextRunTime?: (job: QuestJob) => Date | null,
+ *   executeJob?: (name: string, customInputs?: AnyRecord) => Promise<QuestExecutionResult>,
+ * }} QuestScheduleContext
+ *
+ * @typedef {{
+ *   jobs?: QuestJobsMap,
+ *   scheduleJob?: (name: string) => void,
+ * }} QuestStartContext
+ *
+ * @typedef {{
+ *   jobs?: QuestJobsMap,
+ *   timers?: QuestTimersMap,
+ * }} QuestStopContext
+ *
+ * @typedef {{
+ *   jobs?: QuestJobsMap,
+ *   executeJob?: (name: string, customInputs?: AnyRecord) => Promise<QuestExecutionResult>,
+ * }} QuestRunContext
+ *
+ * @typedef {{
+ *   running?: QuestRunningMap,
+ *   config?: QuestConfig | null,
+ *   stdout?: NodeJS.WritableStream,
+ *   stderr?: NodeJS.WritableStream,
+ * }} QuestExecutorContext
+ *
+ * @typedef {{
+ *   info(...args: any[]): void,
+ *   warn(...args: any[]): void,
+ *   error(...args: any[]): void,
+ *   verbose(...args: any[]): void,
+ *   [key: string]: any,
+ * }} QuestLogger
+ *
+ * @typedef {{
+ *   config: {
+ *     quest: QuestConfig,
+ *     [key: string]: any,
+ *   },
+ *   log: QuestLogger,
+ *   after(eventName: string, handler: Function): void,
+ *   on(eventName: string, handler: Function): void,
+ *   emit(eventName: 'quest:job:start', payload: QuestJobStartEvent): void,
+ *   emit(eventName: 'quest:job:complete', payload: QuestJobCompleteEvent): void,
+ *   emit(eventName: 'quest:job:error', payload: QuestJobErrorEvent): void,
+ *   emit(eventName: string, payload?: any): void,
+ *   quest?: QuestApi,
+ *   [key: string]: any,
+ * }} QuestSailsApp
+ *
+ * @typedef {{
+ *   defaults: { quest: QuestConfig },
+ *   initialize(): Promise<void>,
+ *   [key: string]: any,
+ * }} QuestSailsHook
+ */
+
+module.exports = {}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "sails-hook-quest",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Elegant job scheduling for Sails.js applications with human-readable intervals, cron expressions, and full Sails context",
   "main": "lib/index.js",
   "scripts": {
+    "test": "sounding test",
     "lint": "prettier --check .",
     "lint:fix": "prettier --write .",
+    "typecheck": "tsc -p jsconfig.json --noEmit",
     "prepare": "husky"
   },
   "repository": {
@@ -50,8 +52,11 @@
   "devDependencies": {
     "@commitlint/cli": "^19.5.0",
     "@commitlint/config-conventional": "^19.5.0",
+    "@types/node": "^22.7.5",
     "husky": "^9.1.6",
     "lint-staged": "^15.2.10",
-    "prettier": "^3.3.3"
+    "prettier": "^3.3.3",
+    "sounding": "^0.2.0",
+    "typescript": "^5.6.2"
   }
 }

package/test/executor.test.js

@@ -0,0 +1,95 @@
+const { EventEmitter } = require('node:events')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { Writable } = require('node:stream')
+const { createRuntime, createTestApi } = require('sounding')
+
+const { createDiagnosticTail, executeJob } = require('../lib/core/executor')
+
+const sails = new EventEmitter()
+sails.config = {
+  appPath: process.cwd(),
+  environment: 'test',
+  datastores: {}
+}
+sails.hooks = {}
+sails.helpers = {}
+sails.models = {}
+sails.log = { info() {}, warn() {}, error() {}, verbose() {} }
+
+const test = createTestApi({ runtime: createRuntime(sails) })
+
+test('failed jobs keep live output and emit bounded diagnostics', async ({
+  expect,
+  t
+}) => {
+  const appPath = fs.mkdtempSync(path.join(os.tmpdir(), 'quest-diagnostics-'))
+  const scriptsPath = path.join(appPath, 'scripts')
+  const runnerPath = path.join(appPath, 'fake-sails')
+  fs.mkdirSync(scriptsPath)
+  fs.writeFileSync(path.join(scriptsPath, 'send-issue-notifications.js'), '')
+  fs.writeFileSync(
+    runnerPath,
+    [
+      '#!/usr/bin/env node',
+      "process.stdout.write('Preparing notifications\\n')",
+      "process.stderr.write('Error: database exploded\\n    at sendIssueNotifications (/app/scripts/send-issue-notifications.js:12:3)\\n')",
+      'process.exitCode = 1'
+    ].join('\n')
+  )
+  fs.chmodSync(runnerPath, 0o755)
+
+  const previousSails = global.sails
+  global.sails = sails
+
+  let liveOutput = ''
+  const output = new Writable({
+    write(chunk, encoding, callback) {
+      liveOutput += chunk.toString()
+      callback()
+    }
+  })
+  const failure = new Promise((resolve) =>
+    sails.once('quest:job:error', resolve)
+  )
+
+  t.after(() => {
+    global.sails = previousSails
+    fs.rmSync(appPath, { recursive: true, force: true })
+  })
+
+  let executionError
+  try {
+    await executeJob(
+      'send-issue-notifications',
+      { name: 'send-issue-notifications' },
+      {},
+      {
+        config: { appPath, sailsPath: runnerPath, diagnosticTailBytes: 1024 },
+        stdout: output,
+        stderr: output
+      }
+    )
+  } catch (error) {
+    executionError = error
+  }
+
+  const event = await failure
+  expect(executionError.message).toContain('exited with code 1')
+  expect(liveOutput).toContain('Preparing notifications')
+  expect(liveOutput).toContain('database exploded')
+  expect(event.error.diagnostic).toContain('sendIssueNotifications')
+  expect(event.error.stack).toContain('executor.js')
+})
+
+test('diagnostic tails discard old output at the configured byte limit', ({
+  expect
+}) => {
+  const tail = createDiagnosticTail(12)
+  tail.append('discard-this-')
+  tail.append('keep-this')
+
+  expect(Buffer.byteLength(tail.value())).toBe(12)
+  expect(tail.value()).toBe('is-keep-this')
+})

package/typecheck/public-api-smoke.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+const defineQuestHook = require('../lib')
+const scheduler = require('../lib/core/scheduler')
+const loader = require('../lib/core/loader')
+
+/** @typedef {import('../lib/types').QuestSailsApp} QuestSailsApp */
+/** @typedef {import('../lib/types').QuestNamedJobDefinition} QuestNamedJobDefinition */
+
+/** @type {QuestSailsApp} */
+const sails = {
+  config: {
+    quest: {
+      autoStart: false,
+      timezone: 'UTC',
+      withoutOverlapping: true,
+      jobs: [
+        'cleanup-sessions',
+        {
+          name: 'health-check',
+          interval: '5 minutes',
+          inputs: { url: 'https://example.com/health' }
+        }
+      ]
+    }
+  },
+  log: {
+    info() {},
+    warn() {},
+    error() {},
+    verbose() {}
+  },
+  after(_eventName, handler) {
+    handler()
+  },
+  on() {},
+  emit() {}
+}
+
+const hook = defineQuestHook(sails)
+hook.defaults.quest.jobs.push({
+  name: 'daily-digest',
+  cron: '0 9 * * *',
+  timezone: 'Africa/Lagos'
+})
+
+/** @type {QuestNamedJobDefinition} */
+const dynamicJob = {
+  name: 'dynamic-report',
+  interval: '1 hour',
+  inputs: { format: 'csv' }
+}
+
+sails.quest?.add(dynamicJob)
+sails.quest?.start(['health-check', 'dynamic-report'])
+sails.quest?.run('health-check', { url: 'https://example.com/ping' })
+sails.quest?.pause('dynamic-report')
+sails.quest?.resume('dynamic-report')
+sails.quest?.remove(['dynamic-report'])
+
+const jobs = sails.quest?.list() || []
+const firstJob = jobs[0]
+if (firstJob) {
+  scheduler.getNextRunTime(firstJob, sails.config.quest)
+}
+
+loader.addJobDefinition(
+  {
+    name: 'warm-cache',
+    timeout: '10 minutes',
+    withoutOverlapping: false
+  },
+  new Map(),
+  sails.config.quest
+)
+
+// @ts-expect-error Job names must be strings or string arrays.
+sails.quest?.start(123)
+
+// @ts-expect-error Dynamic jobs need a string name when provided as objects.
+sails.quest?.add({ name: 123, interval: '5 minutes' })
+
+// @ts-expect-error Dynamic job objects need an explicit name.
+sails.quest?.add({ interval: '5 minutes' })