sails-hook-quest 0.0.0 → 0.0.2

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": ["WebFetch(domain:github.com)"],
+    "deny": [],
+    "ask": []
+  }
+}

package/.commitlintrc.js

@@ -0,0 +1 @@
+module.exports = { extends: ['@commitlint/config-conventional'] }

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: DominusKelvin

package/.github/workflows/prettier.yml

@@ -0,0 +1,22 @@
+name: Prettier
+
+on: [push, pull_request]
+
+jobs:
+  prettier:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Run npm ci
+        run: npm ci
+
+      - name: Run Prettier
+        run: npx prettier --config ./.prettierrc.js --write .

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.prettierrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'none'
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 The Sailscasts Company
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,350 @@
+# sails-hook-quest
+
+Elegant job scheduling for Sails.js applications. Run scheduled tasks with full access to your Sails app's models, helpers, and configuration.
+
+## Features
+
+- 🕐 **Multiple scheduling formats** - Cron expressions, human-readable intervals, or specific dates
+- 🚀 **Full Sails context** - Access models, helpers, and config in your jobs
+- 🎯 **Simple API** - Just add a `quest` property to your existing Sails scripts
+- 🔄 **Overlap prevention** - Prevent jobs from running concurrently
+- 📊 **Event system** - Listen to job lifecycle events for monitoring and alerting
+- 🌍 **Environment support** - Run jobs in a minimal 'console' environment for better performance
+
+## Installation
+
+```bash
+npm install sails-hook-quest
+```
+
+## Quick Start
+
+### 1. Create a scheduled job
+
+Create a script in your `scripts/` directory:
+
+```javascript
+// scripts/cleanup-sessions.js
+module.exports = {
+  friendlyName: 'Cleanup old sessions',
+  description: 'Remove expired sessions from the database',
+
+  // Add Quest scheduling configuration
+  quest: {
+    interval: '1 hour', // Human-readable interval
+    // or
+    cron: '0 * * * *', // Standard cron expression
+
+    withoutOverlapping: true // Prevent concurrent runs
+  },
+
+  inputs: {
+    daysOld: {
+      type: 'number',
+      defaultsTo: 30
+    }
+  },
+
+  fn: async function (inputs) {
+    // Full access to Sails models
+    const deleted = await Session.destroy({
+      lastActive: {
+        '<': new Date(Date.now() - inputs.daysOld * 24 * 60 * 60 * 1000)
+      }
+    }).fetch()
+
+    // Use helpers
+    await sails.helpers.sendEmail.with({
+      to: 'admin@example.com',
+      subject: 'Cleanup complete',
+      text: `Deleted ${deleted.length} sessions`
+    })
+
+    return { deletedCount: deleted.length }
+  }
+}
+```
+
+### 2. Configure Quest (optional)
+
+```javascript
+// config/quest.js
+module.exports.quest = {
+  // Auto-start jobs on lift
+  autoStart: true,
+
+  // Timezone for cron expressions
+  timezone: 'UTC',
+
+  // Run jobs in console environment (minimal Sails lift)
+  environment: 'console',
+
+  // Define additional jobs in config
+  jobs: [
+    {
+      name: 'health-check',
+      interval: '5 minutes',
+      inputs: {
+        url: 'https://api.example.com/health'
+      }
+    }
+  ]
+}
+```
+
+### 3. Listen to job events (optional)
+
+```javascript
+// config/bootstrap.js
+module.exports.bootstrap = async function () {
+  // Job started
+  sails.on('quest:job:start', (data) => {
+    console.log(`Job ${data.name} started`)
+  })
+
+  // Job completed
+  sails.on('quest:job:complete', (data) => {
+    console.log(`Job ${data.name} completed in ${data.duration}ms`)
+    // Send metrics to monitoring service
+  })
+
+  // Job failed
+  sails.on('quest:job:error', (data) => {
+    console.error(`Job ${data.name} failed:`, data.error)
+    // Send alert to Slack/Discord/Telegram
+  })
+}
+```
+
+## Scheduling Options
+
+### Human-Readable Intervals
+
+```javascript
+quest: {
+  interval: '30 seconds'
+  interval: '5 minutes'
+  interval: '2 hours'
+  interval: '7 days'
+}
+```
+
+### Cron Expressions
+
+```javascript
+quest: {
+  cron: '0 2 * * *' // Daily at 2 AM
+  cron: '*/5 * * * *' // Every 5 minutes
+  cron: '0 9 * * MON' // Every Monday at 9 AM
+}
+```
+
+### One-time Execution
+
+```javascript
+quest: {
+  timeout: '10 minutes' // Run once after 10 minutes
+  date: new Date('2024-12-25') // Run on specific date
+}
+```
+
+## API
+
+### `sails.quest.run(jobName, inputs?)`
+
+Manually run a job immediately
+
+```javascript
+await sails.quest.run('cleanup-sessions', { daysOld: 7 })
+```
+
+### `sails.quest.start(jobName?)`
+
+Start scheduling a job (or all jobs if no name provided)
+
+```javascript
+sails.quest.start('weekly-report')
+```
+
+### `sails.quest.stop(jobName?)`
+
+Stop scheduling a job
+
+```javascript
+sails.quest.stop('weekly-report')
+```
+
+### `sails.quest.list()`
+
+Get list of all registered jobs
+
+```javascript
+const jobs = sails.quest.list()
+// [{ name: 'cleanup', interval: '1 hour', ... }]
+```
+
+### `sails.quest.pause(jobName)`
+
+Pause a job (prevents execution but keeps schedule)
+
+```javascript
+sails.quest.pause('heavy-task')
+```
+
+### `sails.quest.resume(jobName)`
+
+Resume a paused job
+
+```javascript
+sails.quest.resume('heavy-task')
+```
+
+## Events
+
+Quest emits the following events that you can listen to:
+
+- `quest:job:start` - Job execution started
+- `quest:job:complete` - Job completed successfully
+- `quest:job:error` - Job failed with error
+
+Each event includes:
+
+```javascript
+{
+  name: 'job-name',
+  inputs: { /* job inputs */ },
+  timestamp: Date,
+  duration: 1234,  // milliseconds (complete/error only)
+  error: { }       // error details (error event only)
+}
+```
+
+## Console Environment
+
+Quest can run jobs in a minimal 'console' environment that skips unnecessary hooks for better performance:
+
+```javascript
+// config/env/console.js
+module.exports = {
+  hooks: {
+    views: false,
+    sockets: false,
+    pubsub: false
+    // Only load what your jobs need
+  }
+}
+```
+
+```javascript
+// config/quest.js
+module.exports.quest = {
+  environment: 'console' // Use console environment for jobs
+}
+```
+
+## Examples
+
+### Send Weekly Newsletter
+
+```javascript
+// scripts/send-newsletter.js
+module.exports = {
+  friendlyName: 'Send weekly newsletter',
+
+  quest: {
+    cron: '0 9 * * MON', // Every Monday at 9 AM
+    withoutOverlapping: true
+  },
+
+  fn: async function () {
+    const subscribers = await User.find({
+      subscribed: true,
+      emailVerified: true
+    })
+
+    for (const user of subscribers) {
+      await sails.helpers.sendEmail.newsletter(user)
+    }
+
+    return { sent: subscribers.length }
+  }
+}
+```
+
+### Process Upload Queue
+
+```javascript
+// scripts/process-uploads.js
+module.exports = {
+  friendlyName: 'Process pending uploads',
+
+  quest: {
+    interval: '2 minutes',
+    withoutOverlapping: true
+  },
+
+  fn: async function () {
+    const pending = await Upload.find({
+      status: 'pending'
+    }).limit(10)
+
+    for (const upload of pending) {
+      await sails.helpers.processUpload(upload)
+      await Upload.updateOne({ id: upload.id }).set({ status: 'processed' })
+    }
+
+    return { processed: pending.length }
+  }
+}
+```
+
+### Database Backup
+
+```javascript
+// scripts/backup-database.js
+module.exports = {
+  friendlyName: 'Backup database',
+
+  quest: {
+    cron: '0 3 * * *', // Daily at 3 AM
+    withoutOverlapping: true
+  },
+
+  fn: async function () {
+    const backup = await sails.helpers.createDatabaseBackup()
+
+    await sails.helpers.uploadToS3(backup.path)
+
+    await sails.helpers.sendEmail.with({
+      to: 'admin@example.com',
+      subject: 'Database backup complete',
+      text: `Backup saved: ${backup.filename}`
+    })
+
+    return { filename: backup.filename }
+  }
+}
+```
+
+## How It Works
+
+Quest leverages the existing `sails run` command to execute jobs. Each job runs as a separate Sails process with full access to your application's context. This approach provides:
+
+1. **Full Sails context** - Models, helpers, and config work exactly as expected
+2. **Process isolation** - Jobs can't crash your main application
+3. **Simple implementation** - No complex worker thread communication
+4. **Familiar patterns** - Jobs are just Sails scripts with scheduling metadata
+
+## License
+
+MIT
+
+## Support
+
+- 📖 [Documentation](https://docs.sailscasts.com/sails-quest)
+- 🐛 [Report Issues](https://github.com/sailscastshq/sails-hook-quest/issues)
+- 💬 [Discord Community](https://discord.gg/gbJZuNm)
+
+---
+
+Built with ❤️ by [The Sailscasts Company](https://sailscasts.com)

package/lib/core/executor.js

@@ -0,0 +1,184 @@
+/**
+ * core/executor.js
+ *
+ * Functions for executing jobs via child processes
+ */
+
+const { spawn } = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * 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
+ */
+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) {
+      sails.log.warn(`Job "${name}" is already running, skipping...`)
+    }
+    return { skipped: true, reason: 'already_running' }
+  }
+
+  // Don't run if paused
+  if (job.paused) {
+    if (global.sails) {
+      sails.log.verbose(`Job "${name}" is paused, skipping...`)
+    }
+    return { skipped: true, reason: 'paused' }
+  }
+
+  if (global.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 }
+
+  // Emit job start event
+  if (global.sails) {
+    sails.emit('quest:job:start', {
+      name,
+      inputs,
+      timestamp: new Date()
+    })
+  }
+
+  return new Promise((resolve, reject) => {
+    // Build command arguments
+    const args = buildCommandArgs(name, inputs)
+
+    // Setup environment
+    const env = { ...process.env }
+    if (config.environment) {
+      env.NODE_ENV = config.environment
+    }
+
+    const sailsPath = config.sailsPath || './node_modules/.bin/sails'
+    const cwd = config.appPath || process.cwd()
+    const scriptsDir = config.scriptsDir || 'scripts'
+
+    // Validate script exists before attempting to run
+    const scriptPath = path.resolve(cwd, scriptsDir, `${name}.js`)
+    if (!fs.existsSync(scriptPath)) {
+      running.delete(name)
+      const error = new Error(
+        `Job "${name}" not found. Please check that the script exists at ${scriptsDir}/${name}.js`
+      )
+      if (global.sails) {
+        sails.log.error(error.message)
+        sails.emit('quest:job:error', {
+          name,
+          inputs,
+          error: { message: error.message },
+          duration: 0,
+          timestamp: new Date()
+        })
+      }
+      return reject(error)
+    }
+
+    const child = spawn(sailsPath, args, {
+      cwd,
+      env,
+      stdio: 'inherit'
+    })
+
+    child.on('exit', (code) => {
+      const startTime = running.get(name)
+      const duration = Date.now() - startTime
+      running.delete(name)
+
+      if (code === 0) {
+        if (global.sails) {
+          sails.log.info(`Job "${name}" completed successfully`)
+
+          // Emit success event
+          sails.emit('quest:job:complete', {
+            name,
+            inputs,
+            duration,
+            timestamp: new Date()
+          })
+        }
+
+        resolve({ success: true, duration })
+      } else {
+        const error = new Error(`Job "${name}" exited with code ${code}`)
+
+        if (global.sails) {
+          sails.log.error(error)
+
+          // Emit error event
+          sails.emit('quest:job:error', {
+            name,
+            inputs,
+            error: {
+              message: error.message,
+              code
+            },
+            duration,
+            timestamp: new Date()
+          })
+        }
+
+        reject(error)
+      }
+    })
+
+    child.on('error', (err) => {
+      const startTime = running.get(name) || Date.now()
+      const duration = Date.now() - startTime
+      running.delete(name)
+
+      if (global.sails) {
+        sails.log.error(`Job "${name}" failed to start:`, err)
+
+        // Emit error event
+        sails.emit('quest:job:error', {
+          name,
+          inputs,
+          error: {
+            message: err.message,
+            stack: err.stack
+          },
+          duration,
+          timestamp: new Date()
+        })
+      }
+
+      reject(err)
+    })
+  })
+}
+
+/**
+ * Build command arguments for sails run
+ * @param {String} scriptName - Name of the script
+ * @param {Object} inputs - Input values
+ * @returns {Array} Command arguments
+ */
+function buildCommandArgs(scriptName, inputs = {}) {
+  const args = ['run', scriptName]
+
+  // Add inputs as command line args
+  for (const [key, value] of Object.entries(inputs)) {
+    args.push(`--${key}=${JSON.stringify(value)}`)
+  }
+
+  return args
+}
+
+module.exports = {
+  executeJob,
+  buildCommandArgs
+}

package/lib/core/job-control.js

@@ -0,0 +1,192 @@
+/**
+ * core/job-control.js
+ *
+ * Functions for controlling job lifecycle (start, stop, pause, resume)
+ */
+
+/**
+ * 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
+ */
+function scheduleJob(name, context = {}) {
+  const {
+    jobs = new Map(),
+    timers = new Map(),
+    getNextRunTime,
+    executeJob
+  } = context
+
+  const job = jobs.get(name)
+  if (!job) {
+    if (global.sails) {
+      sails.log.warn(`Job "${name}" not found in jobs Map`)
+    }
+    return
+  }
+
+  // Clear any existing timer
+  stopJob(name, { timers })
+
+  // Get the next run time
+  const nextRun = getNextRunTime(job)
+  if (!nextRun) {
+    if (global.sails) {
+      sails.log.warn(
+        `Job "${name}" has no valid schedule (interval: ${job.interval}, cron: ${job.cron}, timeout: ${job.timeout})`
+      )
+    }
+    return
+  }
+
+  const delay = nextRun.getTime() - Date.now()
+
+  // If delay is negative (past time), run immediately
+  if (delay <= 0) {
+    executeJob(name).catch((err) => {
+      if (global.sails) {
+        sails.log.error(`Error running job "${name}":`, err)
+      }
+    })
+
+    // If it's a recurring job, schedule the next run
+    if (job.interval || job.cron) {
+      scheduleJob(name, context)
+    }
+    return
+  }
+
+  // Set timer for the next execution
+  const timer = setTimeout(() => {
+    executeJob(name).catch((err) => {
+      if (global.sails) {
+        sails.log.error(`Error running job "${name}":`, err)
+      }
+    })
+
+    // If it's a recurring job, schedule the next run
+    if (job.interval || job.cron) {
+      scheduleJob(name, context)
+    }
+  }, delay)
+
+  timers.set(name, timer)
+
+  if (global.sails) {
+    sails.log.verbose(`Job "${name}" scheduled for ${nextRun.toISOString()}`)
+  }
+}
+
+/**
+ * Stop a single job
+ * @param {String} name - Job name
+ * @param {Object} context - Context with timers map
+ */
+function stopJob(name, context = {}) {
+  const { timers = new Map() } = context
+
+  const timer = timers.get(name)
+  if (timer) {
+    clearTimeout(timer)
+    clearInterval(timer)
+    timers.delete(name)
+    if (global.sails) {
+      sails.log.verbose(`Job "${name}" stopped`)
+    }
+  }
+}
+
+/**
+ * Start scheduling jobs
+ * @param {String|Array} jobNames - Job names to start (optional)
+ * @param {Object} context - Context with jobs map and scheduleJob function
+ */
+async function startJobs(jobNames, context = {}) {
+  const { jobs = new Map(), scheduleJob } = context
+
+  const names = !jobNames
+    ? Array.from(jobs.keys())
+    : Array.isArray(jobNames)
+      ? jobNames
+      : [jobNames]
+
+  for (const name of names) {
+    scheduleJob(name)
+  }
+}
+
+/**
+ * Stop scheduling jobs
+ * @param {String|Array} jobNames - Job names to stop (optional)
+ * @param {Object} context - Context with jobs and timers maps
+ */
+function stopJobs(jobNames, context = {}) {
+  const { jobs = new Map(), timers = new Map() } = context
+
+  const names = !jobNames
+    ? Array.from(jobs.keys())
+    : Array.isArray(jobNames)
+      ? jobNames
+      : [jobNames]
+
+  for (const name of names) {
+    stopJob(name, { timers })
+  }
+}
+
+/**
+ * Run jobs immediately
+ * @param {String|Array} jobNames - Job names to run
+ * @param {Object} inputs - Custom inputs
+ * @param {Object} context - Context with executeJob function
+ */
+async function runJobs(jobNames, inputs, context = {}) {
+  const { jobs = new Map(), executeJob } = context
+
+  const names = !jobNames
+    ? Array.from(jobs.keys())
+    : Array.isArray(jobNames)
+      ? jobNames
+      : [jobNames]
+
+  const promises = names.map((name) => executeJob(name, inputs))
+  return Promise.all(promises)
+}
+
+/**
+ * Pause a job
+ * @param {String} name - Job name
+ * @param {Map} jobs - Jobs map
+ */
+function pauseJob(name, jobs = new Map()) {
+  const job = jobs.get(name)
+  if (job) {
+    job.paused = true
+    return true
+  }
+  return false
+}
+
+/**
+ * Resume a job
+ * @param {String} name - Job name
+ * @param {Map} jobs - Jobs map
+ */
+function resumeJob(name, jobs = new Map()) {
+  const job = jobs.get(name)
+  if (job) {
+    job.paused = false
+    return true
+  }
+  return false
+}
+
+module.exports = {
+  scheduleJob,
+  stopJob,
+  startJobs,
+  stopJobs,
+  runJobs,
+  pauseJob,
+  resumeJob
+}

package/lib/core/loader.js

@@ -0,0 +1,196 @@
+/**
+ * core/loader.js
+ *
+ * Functions for loading and managing job definitions
+ */
+
+const path = require('path')
+const includeAll = require('include-all')
+
+/**
+ * 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
+ */
+function extractScriptInputDefaults(inputs) {
+  const defaults = {}
+  if (!inputs || typeof inputs !== 'object') return defaults
+
+  for (const [key, def] of Object.entries(inputs)) {
+    if (def && def.defaultsTo !== undefined) {
+      defaults[key] = def.defaultsTo
+    }
+  }
+  return defaults
+}
+
+/**
+ * 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
+ */
+async function loadJobs(config, jobs = new Map()) {
+  // First, load scripts from the scripts directory
+  const scriptsDir = config.scriptsDir || 'scripts'
+  const appPath = config.appPath || process.cwd()
+  const fullPath = path.resolve(appPath, scriptsDir)
+
+  let scripts = {}
+
+  try {
+    scripts = includeAll({
+      dirname: fullPath,
+      filter: /(.+)\.js$/,
+      excludeDirs: /^\.(git|svn)$/,
+      flatten: true
+    })
+  } catch (e) {
+    if (global.sails) {
+      sails.log.verbose('No scripts directory found, skipping script jobs')
+    }
+  }
+
+  // First, add jobs from config (provides base inputs)
+  if (Array.isArray(config.jobs)) {
+    const configJobNames = new Set()
+
+    for (const jobDef of config.jobs) {
+      // Handle string shorthand (just job name)
+      const job = typeof jobDef === 'string' ? { name: jobDef } : jobDef
+
+      // Check for duplicate job names in config
+      if (configJobNames.has(job.name)) {
+        throw new Error(
+          `Duplicate job name "${job.name}" in config/quest.js. Each job must have a unique name.`
+        )
+      }
+      configJobNames.add(job.name)
+
+      // Try to get script inputs if the script exists
+      const scriptDef = scripts[job.name]
+      if (scriptDef && !job.scriptInputs) {
+        job.scriptInputs = extractScriptInputDefaults(scriptDef.inputs)
+      }
+
+      addJobDefinition(job, jobs, config)
+    }
+  }
+
+  // Then process scripts with quest config (script scheduling takes priority)
+  for (const [scriptFile, scriptDef] of Object.entries(scripts)) {
+    if (!scriptDef.quest) continue
+
+    const scriptName = scriptFile.replace(/\.js$/, '')
+    const questConfig = scriptDef.quest
+    const jobName = questConfig.name || scriptName
+
+    // Extract default values from script's inputs schema
+    const scriptInputs = extractScriptInputDefaults(scriptDef.inputs)
+
+    // Check if job was already defined in config
+    const existingJob = jobs.get(jobName)
+
+    // Merge: config as base, script quest config takes priority
+    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 },
+      ...questConfig,
+      scriptInputs
+    }
+
+    addJobDefinition(jobDef, jobs, config)
+  }
+
+  return jobs
+}
+
+/**
+ * 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
+ */
+function addJobDefinition(jobDef, jobs = new Map(), config = {}) {
+  const name = jobDef.name
+  if (!name) {
+    if (global.sails) {
+      sails.log.warn('Job definition missing name, skipping:', jobDef)
+    }
+    return null
+  }
+
+  // Parse and normalize the job definition
+  const job = {
+    name,
+    friendlyName: jobDef.friendlyName || name,
+    description: jobDef.description,
+
+    // Scheduling options
+    interval: jobDef.interval,
+    timeout: jobDef.timeout,
+    cron: jobDef.cron,
+    cronOptions: jobDef.cronOptions,
+    date: jobDef.date,
+    timezone: jobDef.timezone,
+
+    // Input data to pass to the script
+    inputs: jobDef.inputs || {},
+    scriptInputs: jobDef.scriptInputs || {},
+
+    // Control options
+    paused: false,
+    withoutOverlapping:
+      jobDef.withoutOverlapping ?? config.withoutOverlapping ?? true
+  }
+
+  jobs.set(name, job)
+
+  if (global.sails) {
+    const schedule = {}
+    if (job.interval !== undefined) schedule.interval = job.interval
+    if (job.cron !== undefined) schedule.cron = job.cron
+    if (job.timeout !== undefined) schedule.timeout = job.timeout
+    sails.log.verbose(`Registered job: ${name}`, schedule)
+  }
+
+  return job
+}
+
+/**
+ * Remove a job from the jobs map
+ * @param {String} name - Job name
+ * @param {Map} jobs - Jobs map
+ * @param {Map} timers - Timers map
+ * @returns {Boolean} Success
+ */
+function removeJob(name, jobs = new Map(), timers = new Map()) {
+  // Clear any associated timer
+  if (timers.has(name)) {
+    const timer = timers.get(name)
+    clearTimeout(timer)
+    clearInterval(timer)
+    timers.delete(name)
+  }
+
+  // Remove from jobs map
+  const existed = jobs.delete(name)
+
+  if (existed && global.sails) {
+    sails.log.verbose(`Job "${name}" removed`)
+  }
+
+  return existed
+}
+
+module.exports = {
+  loadJobs,
+  addJobDefinition,
+  removeJob,
+  extractScriptInputDefaults
+}

package/lib/core/scheduler.js

@@ -0,0 +1,203 @@
+/**
+ * core/scheduler.js
+ *
+ * Functions for parsing schedules and calculating next run times
+ */
+
+const later = require('@breejs/later')
+const humanInterval = require('human-interval')
+const { CronExpressionParser } = require('cron-parser')
+
+/**
+ * Parse various schedule formats and return next run time
+ * @param {Object} job - Job configuration
+ * @param {Object} config - Quest configuration
+ * @returns {Date|null} Next run time or null if invalid
+ */
+function getNextRunTime(job, config = {}) {
+  const now = new Date()
+  const timezone = job.timezone || config.timezone
+
+  // Validate: cannot combine date and timeout
+  if (job.date && job.timeout !== undefined && job.timeout !== false) {
+    throw new Error(
+      `Job "${job.name}": Cannot combine 'date' and 'timeout'. Use one or the other.`
+    )
+  }
+
+  // Handle cron expressions
+  if (job.cron) {
+    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()
+    } catch (err) {
+      if (global.sails) {
+        sails.log.error(
+          `Invalid cron expression for job "${job.name}": ${job.cron}`,
+          err.message
+        )
+      }
+      return null
+    }
+  }
+
+  // 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}`)
+    }
+    return null
+  }
+
+  // Handle numeric intervals (milliseconds)
+  if (typeof job.interval === 'number') {
+    return new Date(now.getTime() + job.interval)
+  }
+
+  // Handle timeout (one-time delay)
+  if (job.timeout !== undefined && job.timeout !== false) {
+    return parseTimeout(job.timeout, now)
+  }
+
+  // Handle specific date
+  if (job.date) {
+    const date = new Date(job.date)
+    if (date > now) {
+      return date
+    }
+  }
+
+  return null
+}
+
+/**
+ * Parse an interval string into a Date
+ * @param {String} intervalStr - Interval string like "5 minutes" or "every 2 hours"
+ * @param {Date} fromDate - Calculate from this date
+ * @returns {Date|null} Next run time or null if can't parse
+ */
+function parseInterval(intervalStr, fromDate = new Date()) {
+  // Convert shorthand format (5s, 10m) to human-interval format
+  let processedStr = convertShorthand(intervalStr)
+
+  // Check if it's "every X seconds/minutes" format
+  const everyMatch = processedStr.match(
+    /^every\s+(\d+)\s+(seconds?|minutes?|hours?|days?)$/i
+  )
+  if (everyMatch) {
+    const amount = parseInt(everyMatch[1])
+    const unit = everyMatch[2].replace(/s$/, '') // Remove plural 's'
+    const msMap = {
+      second: 1000,
+      minute: 60000,
+      hour: 3600000,
+      day: 86400000
+    }
+    const ms = amount * msMap[unit]
+    if (ms) {
+      return new Date(fromDate.getTime() + ms)
+    }
+  }
+
+  // Check if it's a later.js text expression
+  if (processedStr.includes('at') || processedStr.includes('on the')) {
+    try {
+      const schedule = later.parse.text(processedStr)
+      if (schedule.error) {
+        throw new Error(schedule.error)
+      }
+      const next = later.schedule(schedule).next(1)
+      if (next) {
+        return new Date(next)
+      }
+    } catch (err) {
+      // Silently continue to try other parsers
+    }
+  }
+
+  // Try human-interval
+  try {
+    const ms = humanInterval(processedStr)
+    if (ms) {
+      return new Date(fromDate.getTime() + ms)
+    }
+  } catch (err) {
+    // Return null if can't parse
+  }
+
+  return null
+}
+
+/**
+ * Parse a timeout value into a Date
+ * @param {String|Number} timeout - Timeout value
+ * @param {Date} fromDate - Calculate from this date
+ * @returns {Date|null} Next run time or null
+ */
+function parseTimeout(timeout, fromDate = new Date()) {
+  // String timeout (human-readable)
+  if (typeof timeout === 'string') {
+    // Check for "at" expressions (e.g., "at 10:00 am")
+    if (timeout.startsWith('at ')) {
+      try {
+        const schedule = later.parse.text(timeout)
+        if (!schedule.error) {
+          const next = later.schedule(schedule).next(1)
+          return next
+        }
+      } catch (err) {}
+    }
+
+    // Try human-interval
+    try {
+      const ms = humanInterval(timeout)
+      if (ms) {
+        return new Date(fromDate.getTime() + ms)
+      }
+    } catch (err) {}
+  }
+
+  // Numeric timeout
+  if (typeof timeout === 'number') {
+    return new Date(fromDate.getTime() + timeout)
+  }
+
+  return null
+}
+
+/**
+ * Convert shorthand format to full format
+ * @param {String} str - Input string
+ * @returns {String} Converted string
+ */
+function convertShorthand(str) {
+  const shorthandMap = {
+    s: ' seconds',
+    m: ' minutes',
+    h: ' hours',
+    d: ' days'
+  }
+
+  // Check for shorthand format like '5s', '10m'
+  const shorthandMatch = str.match(/^(\d+)([smhd])$/)
+  if (shorthandMatch) {
+    return shorthandMatch[1] + shorthandMap[shorthandMatch[2]]
+  }
+
+  return str
+}
+
+module.exports = {
+  getNextRunTime,
+  parseInterval,
+  parseTimeout,
+  convertShorthand
+}

package/lib/index.js

@@ -0,0 +1,140 @@
+/**
+ * sails-hook-quest
+ *
+ * Elegant job scheduling for Sails.js with powerful scheduling syntax
+ * Execute scripts via `sails run` to maintain full Sails context
+ */
+
+const scheduler = require('./core/scheduler')
+const executor = require('./core/executor')
+const loader = require('./core/loader')
+const jobControl = require('./core/job-control')
+
+module.exports = function defineQuestHook(sails) {
+  const jobs = new Map()
+  const timers = new Map()
+  const running = new Map()
+
+  // Create context object that will be passed to modules
+  const context = {
+    jobs,
+    timers,
+    running,
+    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
+    getNextRunTime: null // Will be set after config is available
+  }
+
+  return {
+    defaults: {
+      quest: {
+        // Whether to start jobs automatically
+        autoStart: true,
+
+        // Timezone for cron expressions
+        timezone: 'UTC',
+
+        // Prevent overlapping runs by default
+        withoutOverlapping: true,
+
+        // Path to sails executable
+        sailsPath: './node_modules/.bin/sails',
+
+        // Environment to run jobs in (e.g., 'console' for minimal Sails lift)
+        environment: 'console',
+
+        // Directory containing job scripts
+        scriptsDir: 'scripts',
+
+        // Jobs defined in config
+        jobs: []
+      }
+    },
+
+    initialize: async function () {
+      sails.log.info('Initializing Quest job scheduler')
+
+      sails.after('hook:orm:loaded', async () => {
+        // Set up context with config
+        context.config = sails.config.quest
+        context.getNextRunTime = (job) =>
+          scheduler.getNextRunTime(job, sails.config.quest)
+        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
+            const minimalJob = {
+              name,
+              withoutOverlapping: false,
+              inputs: {}
+            }
+            return executor.executeJob(name, minimalJob, customInputs, context)
+          }
+          return executor.executeJob(name, job, customInputs, context)
+        }
+
+        // Load jobs from scripts and config
+        await loader.loadJobs(sails.config.quest, jobs)
+
+        // Start all jobs if autoStart is enabled
+        if (sails.config.quest.autoStart) {
+          await jobControl.startJobs(null, context)
+        }
+
+        // Expose the Quest API
+        sails.quest = {
+          // Core job control
+          start: (jobNames) => jobControl.startJobs(jobNames, context),
+          stop: (jobNames) => jobControl.stopJobs(jobNames, context),
+          run: (jobNames, inputs) =>
+            jobControl.runJobs(jobNames, inputs, context),
+          add: (jobDefs) => {
+            const defs = Array.isArray(jobDefs) ? jobDefs : [jobDefs]
+            const added = []
+            for (const def of defs) {
+              const job = typeof def === 'string' ? { name: def } : def
+              loader.addJobDefinition(job, jobs, context.config)
+              added.push(job.name)
+              if (context.config.autoStart) {
+                jobControl.scheduleJob(job.name, context)
+              }
+            }
+            return added
+          },
+          remove: (jobNames) => {
+            const names = Array.isArray(jobNames) ? jobNames : [jobNames]
+            const removed = []
+            for (const name of names) {
+              if (loader.removeJob(name, jobs, timers)) {
+                removed.push(name)
+              }
+            }
+            return removed
+          },
+
+          // Job information
+          jobs: Array.from(jobs.values()),
+
+          // Additional helpers
+          list: () => Array.from(jobs.values()),
+          get: (name) => jobs.get(name),
+          isRunning: (name) => running.has(name),
+
+          // Pause/resume
+          pause: (name) => jobControl.pauseJob(name, jobs),
+          resume: (name) => jobControl.resumeJob(name, jobs)
+        }
+
+        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)
+      })
+    }
+  }
+}

package/package.json

@@ -1,27 +1,57 @@
 {
   "name": "sails-hook-quest",
-  "version": "0.0.0",
-  "description": "Seamlessly schedule tasks and scripts in your Sails applications.",
-  "main": "index.js",
+  "version": "0.0.2",
+  "description": "Elegant job scheduling for Sails.js applications with human-readable intervals, cron expressions, and full Sails context",
+  "main": "lib/index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "lint": "prettier --check .",
+    "lint:fix": "prettier --write .",
+    "prepare": "husky"
   },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/sailscastshq/sails-hook-quest.git"
+  },
+  "bugs": "https://github.com/sailscastshq/sails-hook-quest/issues",
   "keywords": [
     "sails",
     "sails.js",
+    "sailsjs",
     "hook",
+    "sails-hook",
     "scheduler",
-    "task automation",
-    "scheduling",
-    "automated tasks",
-    "task management",
-    "dynamic scheduling",
-    "Sails.js scripts"
+    "job-scheduler",
+    "cron",
+    "cron-jobs",
+    "task-scheduler",
+    "background-jobs",
+    "job-queue",
+    "automated-tasks",
+    "scheduled-tasks",
+    "human-readable",
+    "sails-scripts"
   ],
-  "author": "",
-  "icense": "MIT",
+  "author": "Kelvin Omereshone <kelvin@sailscasts.com>",
+  "license": "MIT",
   "sails": {
     "isHook": true,
     "hookName": "quest"
+  },
+  "lint-staged": {
+    "**/*": "prettier --write --ignore-unknown"
+  },
+  "dependencies": {
+    "@breejs/later": "^4.2.0",
+    "@sailshq/lodash": "^3.10.6",
+    "cron-parser": "^5.4.0",
+    "human-interval": "^2.0.1",
+    "include-all": "^4.0.3"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.5.0",
+    "@commitlint/config-conventional": "^19.5.0",
+    "husky": "^9.1.6",
+    "lint-staged": "^15.2.10",
+    "prettier": "^3.3.3"
   }
 }