sails-hook-quest 0.0.5 → 0.0.6

package/lib/index.js

@@ -11,6 +11,8 @@ const scheduler = require('./core/scheduler')
 const executor = require('./core/executor')
 const loader = require('./core/loader')
 const jobControl = require('./core/job-control')
+const resident = require('./core/runtime')
+const { isExecutionChild } = require('./core/execution-child')
 
 /** @typedef {import('./types').AnyRecord} AnyRecord */
 /** @typedef {import('./types').QuestApi} QuestApi */
@@ -44,6 +46,10 @@ function defineQuestHook(sails) {
     jobs,
     timers,
     running,
+    sails,
+    runtime: resident.createRuntime(),
+    dueTimes: new Map(),
+    scheduleStates: new Map(),
     config: null, // Will be set after sails.config is available
     scheduleJob: null, // Will be set after function is defined
     executeJob: null, // Will be set after function is defined
@@ -74,6 +80,9 @@ function defineQuestHook(sails) {
         // Maximum child output retained on failure (live output remains unbounded)
         diagnosticTailBytes: 64 * 1024,
 
+        resultBytes: 64 * 1024,
+        inputBytes: 64 * 1024,
+
         // Jobs defined in config
         jobs: []
       }
@@ -82,15 +91,33 @@ function defineQuestHook(sails) {
     initialize: async function () {
       sails.log.info('Initializing Quest job scheduler')
 
-      sails.after('hook:orm:loaded', async () => {
-        const questConfig = sails.config.quest
+      // Register cleanup before awaiting dependencies so failed lift also stops timers.
+      sails.on('lower', async () => {
+        sails.log.info('Stopping Quest jobs...')
+        await jobControl.stopJobs(null, context)
+      })
+
+      const initializeAfterOrm = async () => {
+        // The owned CLI child needs the app's hooks/context, but must not start
+        // another copy of its resident schedules, even if source config enables it.
+        if (isExecutionChild()) sails.config.quest.autoStart = false
+        const questConfig = {
+          ...sails.config.quest,
+          appPath:
+            sails.config.quest.appPath || sails.config.appPath || process.cwd()
+        }
 
         // Set up context with config
         context.config = questConfig
         context.getNextRunTime = (job) =>
-          scheduler.getNextRunTime(job, questConfig)
+          scheduler.getNextRunTime(job, questConfig, (assessment) => {
+            context.scheduleStates.set(job.name, {
+              ...context.scheduleStates.get(job.name),
+              ...assessment
+            })
+          })
         context.scheduleJob = (name) => jobControl.scheduleJob(name, context)
-        context.executeJob = (name, customInputs) => {
+        context.executeJob = (name, customInputs, trigger = 'manual') => {
           const job = jobs.get(name)
           if (!job) {
             // Try to run as a regular script without quest config
@@ -100,9 +127,15 @@ function defineQuestHook(sails) {
               withoutOverlapping: false,
               inputs: {}
             }
-            return executor.executeJob(name, minimalJob, customInputs, context)
+            return executor.executeJob(name, minimalJob, customInputs, {
+              ...context,
+              trigger
+            })
           }
-          return executor.executeJob(name, job, customInputs, context)
+          return executor.executeJob(name, job, customInputs, {
+            ...context,
+            trigger
+          })
         }
 
         // Load jobs from scripts and config
@@ -129,6 +162,7 @@ function defineQuestHook(sails) {
               /** @type {QuestNamedJobDefinition} */
               const job = typeof def === 'string' ? { name: def } : def
               loader.addJobDefinition(job, jobs, context.config || {})
+              context.scheduleStates.delete(job.name)
               added.push(job.name)
               if (context.config?.autoStart) {
                 jobControl.scheduleJob(job.name, context)
@@ -141,12 +175,17 @@ function defineQuestHook(sails) {
             const removed = []
             for (const name of names) {
               if (loader.removeJob(name, jobs, timers)) {
+                context.dueTimes.delete(name)
+                context.scheduleStates.delete(name)
                 removed.push(name)
               }
             }
             return removed
           },
 
+          getRuntime: () => resident.runtimeInfo(context),
+          metadata: (name) => resident.metadata(context, name),
+
           // Job information
           jobs: Array.from(jobs.values()),
 
@@ -162,12 +201,14 @@ function defineQuestHook(sails) {
 
         sails.quest = questApi
         sails.log.info(`Quest started with ${jobs.size} scheduled job(s)`)
-      })
+      }
 
-      // Graceful shutdown
-      sails.on('lower', async () => {
-        sails.log.info('Stopping Quest jobs...')
-        await jobControl.stopJobs(null, context)
+      // Sails waits for this Promise before marking Quest loaded. ORM initializes
+      // independently; after() also handles an ORM event that already occurred.
+      await new Promise((resolve, reject) => {
+        sails.after('hook:orm:loaded', () => {
+          initializeAfterOrm().then(resolve, reject)
+        })
       })
     }
   }

package/lib/types.js

@@ -10,11 +10,11 @@
  *
  * @typedef {JsonPrimitive | any[] | AnyRecord} JsonValue
  *
- * @typedef {string | number} QuestInterval
+ * @typedef {string | number | false} QuestInterval
  *
  * @typedef {string | number | false} QuestTimeout
  *
- * @typedef {string | number | Date} QuestDateInput
+ * @typedef {string | number | Date | false} QuestDateInput
  *
  * @typedef {Record<string, any>} QuestCronOptions
  *
@@ -52,6 +52,8 @@
  *
  * @typedef {{
  *   name: string,
+ *   script?: string,
+ *   inputSchema?: QuestMachineInputs,
  *   friendlyName: string,
  *   description?: string,
  *   interval?: QuestInterval,
@@ -68,6 +70,8 @@
  *
  * @typedef {{
  *   name: string,
+ *   script?: string,
+ *   inputSchema?: QuestMachineInputs,
  *   inputs?: AnyRecord,
  *   scriptInputs?: AnyRecord,
  *   paused?: boolean,
@@ -101,23 +105,66 @@
  * @typedef {{
  *   skipped: true,
  *   reason: 'already_running' | 'paused',
+ *   runId?: string,
+ *   runtimeId?: string,
+ *   startedAt?: Date,
+ *   trigger?: 'manual' | 'scheduled',
+ *   finishedAt?: Date,
+ *   exitCode?: number | null,
+ *   signal?: string | null,
  * }} QuestSkippedResult
  *
  * @typedef {{
  *   success: true,
  *   duration: number,
+ *   runId?: string,
+ *   runtimeId?: string,
+ *   sequence?: number,
+ *   startedAt?: Date,
+ *   trigger?: 'manual' | 'scheduled',
+ *   finishedAt?: Date,
+ *   exitCode?: number | null,
+ *   signal?: string | null,
+ *   result?: QuestBusinessResult,
+ *   logs?: QuestLogs,
  * }} QuestSuccessResult
  *
+ * @typedef {{status: string, value?: any, reason?: string, exit?: string}} QuestBusinessResult
+ *
+ * @typedef {{stdout: string, stderr: string, stdoutTruncated: boolean, stderrTruncated: boolean, limitBytes: number}} QuestLogs
+ *
+ * @typedef {{runtimeId: string, sequence: number, active: Map<string, Map<string, number>>}} QuestRuntime
+ *
  * @typedef {QuestSkippedResult | QuestSuccessResult} QuestExecutionResult
  *
  * @typedef {{
  *   name: string,
+ *   runId?: string,
+ *   runtimeId?: string,
+ *   sequence?: number,
+ *   startedAt?: Date,
+ *   trigger?: 'manual' | 'scheduled',
+ *   finishedAt?: Date,
+ *   exitCode?: number | null,
+ *   signal?: string | null,
+ *   result?: QuestBusinessResult,
+ *   logs?: QuestLogs,
  *   inputs: AnyRecord,
  *   timestamp: Date,
  * }} QuestJobStartEvent
  *
  * @typedef {{
  *   name: string,
+ *   runId?: string,
+ *   runtimeId?: string,
+ *   sequence?: number,
+ *   startedAt?: Date,
+ *   trigger?: 'manual' | 'scheduled',
+ *   finishedAt?: Date,
+ *   exitCode?: number | null,
+ *   signal?: string | null,
+ *   result?: QuestBusinessResult,
+ *   logs?: QuestLogs,
  *   inputs: AnyRecord,
  *   duration: number,
  *   timestamp: Date,
@@ -132,6 +179,16 @@
  *
  * @typedef {{
  *   name: string,
+ *   runId?: string,
+ *   runtimeId?: string,
+ *   sequence?: number,
+ *   startedAt?: Date,
+ *   trigger?: 'manual' | 'scheduled',
+ *   finishedAt?: Date,
+ *   exitCode?: number | null,
+ *   signal?: string | null,
+ *   result?: QuestBusinessResult,
+ *   logs?: QuestLogs,
  *   inputs: AnyRecord,
  *   error: QuestJobErrorDetails,
  *   duration: number,
@@ -144,6 +201,8 @@
  *   run(jobNames?: QuestJobNameInput, inputs?: AnyRecord): Promise<QuestExecutionResult[]>,
  *   add(jobDefs: QuestJobDefinitionInput | QuestJobDefinitionInput[]): string[],
  *   remove(jobNames: QuestJobNameInput): string[],
+ *   getRuntime(): AnyRecord,
+ *   metadata(name?: string): AnyRecord | AnyRecord[] | undefined,
  *   jobs: QuestJob[],
  *   list(): QuestJob[],
  *   get(name: string): QuestJob | undefined,
@@ -162,17 +221,23 @@
  *   jobs: QuestJobsMap,
  *   timers: QuestTimersMap,
  *   running: QuestRunningMap,
+ *   sails: QuestSailsApp,
+ *   runtime: QuestRuntime,
+ *   dueTimes: Map<string, Date>,
+ *   scheduleStates?: Map<string, AnyRecord>,
  *   config: QuestConfig | null,
  *   scheduleJob: ((name: string) => void) | null,
- *   executeJob: ((name: string, customInputs?: AnyRecord) => Promise<QuestExecutionResult>) | null,
+ *   executeJob: ((name: string, customInputs?: AnyRecord, trigger?: 'manual' | 'scheduled') => Promise<QuestExecutionResult>) | null,
  *   getNextRunTime: ((job: QuestJob) => Date | null) | null,
  * }} QuestContext
  *
  * @typedef {{
  *   jobs?: QuestJobsMap,
  *   timers?: QuestTimersMap,
+ *   dueTimes?: Map<string, Date>,
+ *   scheduleStates?: Map<string, AnyRecord>,
  *   getNextRunTime?: (job: QuestJob) => Date | null,
- *   executeJob?: (name: string, customInputs?: AnyRecord) => Promise<QuestExecutionResult>,
+ *   executeJob?: (name: string, customInputs?: AnyRecord, trigger?: 'manual' | 'scheduled') => Promise<QuestExecutionResult>,
  * }} QuestScheduleContext
  *
  * @typedef {{
@@ -183,15 +248,20 @@
  * @typedef {{
  *   jobs?: QuestJobsMap,
  *   timers?: QuestTimersMap,
+ *   dueTimes?: Map<string, Date>,
+ *   scheduleStates?: Map<string, AnyRecord>,
  * }} QuestStopContext
  *
  * @typedef {{
  *   jobs?: QuestJobsMap,
- *   executeJob?: (name: string, customInputs?: AnyRecord) => Promise<QuestExecutionResult>,
+ *   executeJob?: (name: string, customInputs?: AnyRecord, trigger?: 'manual' | 'scheduled') => Promise<QuestExecutionResult>,
  * }} QuestRunContext
  *
  * @typedef {{
+ *   trigger?: 'manual' | 'scheduled',
  *   running?: QuestRunningMap,
+ *   sails?: QuestSailsApp,
+ *   runtime?: QuestRuntime,
  *   config?: QuestConfig | null,
  *   stdout?: NodeJS.WritableStream,
  *   stderr?: NodeJS.WritableStream,

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "sails-hook-quest",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Elegant job scheduling for Sails.js applications with human-readable intervals, cron expressions, and full Sails context",
   "main": "lib/index.js",
+  "files": [
+    "lib",
+    "README.md",
+    "CONTRACT.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
     "test": "sounding test",
     "lint": "prettier --check .",
@@ -56,6 +63,8 @@
     "husky": "^9.1.6",
     "lint-staged": "^15.2.10",
     "prettier": "^3.3.3",
+    "sails": "^1.5.18",
+    "sails-hook-orm": "^4.0.3",
     "sounding": "^0.2.0",
     "typescript": "^5.6.2"
   }

package/.claude/settings.local.json

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

package/.commitlintrc.js

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

package/.github/FUNDING.yml

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

package/.github/workflows/prettier.yml

@@ -1,22 +0,0 @@
-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

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

package/.prettierrc.js

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

package/jsconfig.json

@@ -1,17 +0,0 @@
-{
-  "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/test/executor.test.js

@@ -1,95 +0,0 @@
-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

@@ -1,84 +0,0 @@
-// @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' })