sails-hook-quest 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## 0.0.6
+
+Quest now exposes the resident execution contract required by job-management integrations while keeping schedules in application source.
+
+### Added
+
+- Process-local runtime identity and capability probes, sanitized input/schema metadata, effective scheduled input previews, running counts, pause state and actual registered timer targets.
+- Stable run identity and manual/scheduled provenance on lifecycle events and receipts. Terminal outcomes preserve numeric process exit codes and observed termination signals separately from machine business exits.
+- Actual machine business results over a dedicated bounded channel, independent of stdout/stderr. Null, false and zero remain values; unsupported, oversized and nonserializable results are reported explicitly. Bounded diagnostic tails include warnings from successful jobs.
+- Bounded schedule registration/validation diagnostics, effective cron timezone precedence and memory-only restart semantics.
+
+### Fixed
+
+- Invalid inputs for source-loaded jobs reject before child launch with `E_QUEST_ADMISSION_REJECTED`, preserving the original Sails validation code. Loaded empty schemas reject unknown inputs; dynamic jobs without metadata keep child-side validation.
+- Quest initialization completes only after ORM readiness, jobs and automatic schedules are loaded, and `sails.quest` is published. Successful loaded/ready events and lift callbacks can use the API immediately. Initialization failures reject Sails loading/lifting.
+- Owned Sails CLI job children suppress their own automatic Quest schedules after source configuration loads. The resident retains scheduler authority and the child retains application hooks/context.
+- Unsafe zero/negative/non-finite/out-of-range recurring intervals and invalid dates/timeouts register no timer. Numeric timeouts must be nonnegative; zero remains an immediate one-shot. These are intentional changes for invalid configuration. Valid expired dates and exhausted cron ranges report no future run rather than invalid configuration.
+- Source config aliases preserve original script/schema identity. Allowed overlap state lasts until the final active child completes, and intermediate long-delay timers retain their original target.
+- JSON/ref CLI inputs use schema-aware JSON encoding, including ordinary strings, `001` and empty text, while ordinary string inputs keep their literal semantics. Invalid schedules do not prevent an independent manual run with valid business inputs.
+
+### Compatibility and limits
+
+Existing public job-control methods and lifecycle event names remain. New metadata, receipt and event fields are additive. Input precedence remains `job.inputs < scriptInputs < manual inputs`. Pause does not terminate active children; stopping removes future scheduling. All resident scheduling, diagnostics, runtime identity and consumed state are memory-only. Relative intervals/timeouts restart from registration; missed runs are not replayed.
+
+There is no cancellation API, durable execution ledger, distributed lock, workflow builder, second scheduler, automatic retry or transport server. Consumers own transport, authorization, persistence and recovery. See [CONTRACT.md](CONTRACT.md) for exact shapes, bounds and capability gating.

package/CONTRACT.md

@@ -0,0 +1,97 @@
+# Resident Quest contract (v1)
+
+This contract is introduced in Quest 0.0.6 for upstream issue [#13](https://github.com/sailscastshq/sails-hook-quest/issues/13), based on the previous v0.0.5 source (`3588713`). Probe `getRuntime().contractVersion` and capabilities; released v0.0.5 has none of these new APIs.
+
+## Resident metadata
+
+`getRuntime()` returns a runtime UUID, `contractVersion: 1`, `scope: 'process'`, and capabilities for input metadata, business results, run identity, and resident state, plus explicit childSchedulerSuppression/triggerProvenance/terminalExitCode/terminalSignal probes. Cancellation and durable history are explicitly false.
+
+`metadata()` returns the current registered jobs; `metadata(name)` returns one job or undefined. Each job includes name, original script identity, friendly name/description, `inputMetadataAvailable`, sanitized keyed machine input schema, source-owned schedule, paused/withoutOverlapping flags, active running count, actual timer registration, timer target ISO timestamp (`nextRunAt`, otherwise null), and runtime UUID. Reading metadata neither schedules nor invokes jobs. Pausing blocks new admission and leaves active runs untouched. Timers can stay registered while paused. Stopping removes scheduling, rather than cancelling a child. Pause and scheduling state are process-local and reset when the resident application restarts.
+
+The input schema contains safe JSON constraints, defaults, and examples. Functions are omitted; `customValidation` indicates a custom rule without executing it. Protected/sensitive fields and credential-like names omit defaults/examples. Schema metadata is descriptive, not a substitute for machine validation. `inputMetadataAvailable` is true for source-loaded schemas, including a genuinely empty schema, and false for dynamically added/unloaded definitions without one. In the latter case `inputs: {}` does not claim that the script takes no inputs or supports preflight; typed invocation consumers must gate on the per-job flag. Loaded empty schemas still reject unknown supplied inputs before spawning.
+
+`getRuntime().capabilities.scheduleDiagnostics` signals parser-backed schedule assessments. Each job's additive `scheduleState` is:
+
+```js
+{
+  registration: 'not_attempted', // registered | not_registered | stopped | consumed | failed
+  validation: 'not_checked', // valid | invalid
+  validationErrors: [], // at most one {code, message}, fixed messages under 256 bytes total
+  reason: null, // no_schedule | no_future_run
+  lastAttemptAt: null, // ISO timestamp of last registration attempt
+  restart: {
+    persistence: 'memory_only',
+    timing: 'relative_to_registration', // wall_clock | none
+    oneShot: false,
+    missedRuns: 'not_replayed'
+  }
+}
+```
+
+Assessments are recorded during registration, not invented by metadata reads. `not_checked` with an empty error list does not mean valid. Stopping or consuming a timer retains the last validation assessment; a missing timer alone never means invalid. A valid past date or exhausted cron range reports `valid` with `no_future_run`. No schedule reports `not_checked` with `no_schedule`. Invalid registrations return no timer with one of `E_SCHEDULE_CRON`, `E_SCHEDULE_INTERVAL`, `E_SCHEDULE_TIMEOUT`, or `E_SCHEDULE_DATE`; the existing date/timeout conflict still rejects `start()` and records `E_SCHEDULE_CONFLICT`. Errors use fixed messages without raw parser output. Parser validation concerns schedules only: it does not validate scheduled business inputs or prevent an independent manual run.
+
+Numeric intervals must be finite, strictly positive, and produce a finite future date. Invalid, zero, negative, infinite, or out-of-range recurring intervals now register no timer instead of risking immediate recursion or an overflow timer. Numeric timeouts must be finite and nonnegative; zero remains an immediate one-shot. Invalid date objects and unsupported date/timeout values register no timer. These are intentional safety changes for malformed configurations. Existing valid schedules, source ownership, overlap guards, pause behavior and manual invocation remain.
+
+Intervals and delay timeouts start their relative clock on each registration, including resident restart. Cron, absolute dates and supported wall-clock text schedules keep wall-clock semantics. A one-shot delay may run again after restart when source `autoStart` registers it anew; it is not persisted as consumed. Expired absolute dates do not replay. Scheduling, pause, registration diagnostics and consumed state are memory-only. `nextRunAt` always comes from an actual registered timer, including long-delay intermediate timers.
+
+For cron jobs, `schedule.timezone` reports the effective parser timezone: explicit `cronOptions.tz` overrides the job timezone, then hook timezone. An explicit empty/undefined `tz` override or missing timezone is `null`, meaning the parser's local default. `cronOptions` is preserved as bounded source metadata. `cronOptions.timezone` is not a recognized override. DST follows cron-parser in the effective zone; consumers must use the resident's registered `nextRunAt`, rather than calculate another schedule.
+
+Config aliases use `{name: 'index-from-config', script: 'rebuild-search-index', interval: 10000, inputs: {count: 3}}`. Their schema/defaults come from the original script; events, schedules and overlap guards use the alias's job name. Two aliases intentionally have separate per-job guards, not a script-wide lock.
+
+`scheduledInputs` is separate from schema and manual overrides:
+
+```js
+{
+  values: {count: 0, enabled: false, payload: null},
+  fields: {
+    count: {source: 'script_input', sensitive: false, available: true, missingRequired: false},
+    requiredValue: {source: 'omitted', sensitive: false, available: false, missingRequired: true},
+    secretToken: {source: 'script_input', sensitive: true, available: false, missingRequired: false, reason: 'sensitive'}
+  },
+  validation: 'not_checked',
+  limitBytes: 65536
+}
+```
+
+These are raw effective scheduled values under the existing precedence `job.inputs < scriptInputs < manual inputs`. Machine schema defaults apply when a value is omitted; `schema_default` describes that fallback. `job_input` and `omitted` are the other source markers. Manual inputs do not change configured scheduled values. No sensitive values are included. Non-JSON, oversized, or budget-limited metadata reports `serialization_error`, `too_large`, or `metadata_limit` instead of a preview. Value previews are capped at 4 KiB per field and 64 KiB total. `missingRequired` flags omitted required values; `validation: 'not_checked'` deliberately does not claim custom/type validation passed.
+
+## Execution and events
+
+The existing signature remains `await sails.quest.run('job-name', inputs)` and returns a receipt array. Multiple names and omitted names retain their existing behavior. Admission checks pause/overlap, validates bounded JSON input and loaded machine schemas without executing business logic, and starts the owned `sails run` child. For source-loaded registered jobs, required/type/custom/unknown-key failures reject before the synchronous start event and before any child is spawned. Ad-hoc scripts or dynamically added jobs lacking loaded schema retain child-side validation; they must not be advertised as supporting full preflight admission. The child's installed Sails/whelk machine runner also validates before invoking the script, using exact typed input through a dedicated pipe. Actual machine output, including named exits, crosses another pipe; stdout is never parsed as a result.
+
+Subscribe to `quest:job:start` before calling `run` to capture the synchronous admission run ID before the child starts. Existing start/complete/error event names and payload fields remain. They gain `runId`, `runtimeId`, `sequence`, `startedAt`, and `trigger: 'manual' | 'scheduled'`; `manual` means public/programmatic `run()`, not an actor or a dashboard attribution; both timer paths supply `scheduled` explicitly. Skips, rejected errors and receipts carry the same trigger; terminal events gain `finishedAt`. Sequence increases across this resident runtime. Skips have a new `quest:job:skip` event and an identified receipt. Admission/validation failures return a rejected Promise (the public `run()` does not synchronously throw), with `error.code: 'E_QUEST_ADMISSION_REJECTED'`, `admission: 'rejected_before_start'`, and `phase: 'validation'`. The original Sails code, such as `E_INVALID_ARGINS`, is retained as `validationCode`. They reject without spawning and have no start event; the error event carries the same admission marker and `error.admissionCode`/`validationCode`. A transport error without this verified marker must not be inferred to be preflight rejection.
+
+A normal terminal receipt looks like:
+
+```js
+{
+  success: true, duration: 172,
+  runId: '...', runtimeId: '...', sequence: 2,
+  startedAt: new Date(), finishedAt: new Date(),
+  result: {status: 'available', value: {count: 0}},
+  logs: {stdout: '...', stderr: 'successful warning',
+    stdoutTruncated: false, stderrTruncated: false, limitBytes: 65536}
+}
+```
+
+`result.status` can be `available`, `undefined`, `unsupported`, `too_large`, or `serialization_error`. Null, false, zero, arrays, and plain JSON objects retain their values. Cycles, getters, non-finite numbers, BigInt, Date/class instances, undefined nested properties, and other non-JSON values are not silently coerced. Depth/node limits also bound traversal. Missing, corrupt, or mismatched envelopes report unsupported with a reason. A successful process does not establish business success.
+
+Sails/whelk deliberately exits process 0 for named machine exits. Preserve that process receipt and expose the actual exit separately: `{success: true, result: {status: 'available', value: 'bad', exit: 'invalid'}}`. A named exit with undefined or unrepresentable data still includes its exit beside the appropriate result status. Errors and non-zero processes reject; their error/event retains bounded diagnostics, identity, duration, and separate log tails. Terminal events, receipts and rejected Errors include `exitCode` as the actual numeric child close code or null when no numeric close code exists. Legacy terminal `event.error.code` remains numeric/null. A generated non-zero rejected Error has no `code`; a native spawn Error retains its string `code` (for example ENOENT) and has `exitCode: null`. Pre-spawn admission rejection has the dedicated string code and no exitCode, because no child existed.
+
+`resultBytes`, `inputBytes`, and `logBytes` each default to 64 KiB and have a 1 MiB hard cap. Logs are independent stdout/stderr tails, with truncation flags; live console output and failure diagnostic tails are retained. No per-run live log-stream API is added.
+
+## Reliability boundary
+
+There is no upstream `readRun`, persisted ledger, event replay, cancellation, distributed lock, second scheduler, workflow builder, or automatic retry. Consumers own their transport, access controls, run correlation, durable retention and reconnection. After resident restart or delivery loss they must label missing evidence as unknown/interrupted rather than fabricate a completed run or retry work. A receipt with missing result transport reports unavailability honestly.
+
+The result transport uses a narrowly scoped CommonJS preload in the owned Sails CLI process, matching only this script's machine completion. The preload marks only this process as an owned execution child. After source config is loaded, its Quest hook sets effective `autoStart: false`, keeping hooks and script context available while registering no automatic schedules. The authoritative resident's source `autoStart` and timers remain intact, and the marker is not inherited by other processes. Other application helpers and script implementations keep their behavior. A custom non-Node runner may complete successfully with unsupported result transport. Validate against each supported Sails/Node version before release; the tests include real Sails CLI, resident Sails/ORM, named exits, and two independent resident processes.
+
+## Local verification
+
+Run `npm ci`, `npm test`, `npm run typecheck`, and `npm run lint`. Tests execute synthetic disposable jobs only. The benchmark is `QUEST_BASELINE_PATH=/absolute/path/to/released/lib/core/executor.js node bench/runtime-contract.js`; it alternates release/current CLI executions for quiet, 2 MiB log, and error cases, then measures bounded serialization/diagnostic copying. Benchmark numbers are samples of this machine, not distributed throughput or exact zero-regression guarantees.
+
+`getRuntime().capabilities.terminalSignal` indicates observed Node child-process signals. Terminal complete/error events, success receipts and rejected terminal errors carry `signal: string | null` alongside `exitCode: number | null`. A normal numeric exit or native spawn failure has `signal: null`; an observed `SIGTERM` termination has `exitCode: null, signal: 'SIGTERM'`. Pre-admission rejections and skips have neither terminal field. Named machine exits remain business `result.exit`, independent of the process exit/signal. The signal is the actual owned child's `close` signal; it does not imply who sent it, requested cancellation, or successful cancellation. Cancellation capability remains false.
+
+Quest's async `initialize()` completes only after ORM has loaded, jobs have loaded, source auto-start scheduling has completed, and `sails.quest` has been published. The hook's loaded event, Sails `ready` event and successful full-lift callback can therefore consume the API without a delay or retry. Initialization failures reject Sails loading/lifting instead of escaping through an async event listener or publishing a partial API. Lower cleanup is installed before dependency waiting; owned child auto-start suppression still occurs after source configuration loads.
+
+For source-loaded schemas, JSON/ref inputs use JSON-encoded CLI values even when the supplied value is a string (`'001'`, empty text, or ordinary text). This satisfies whelk's JSON syntax check before its machine invocation; the dedicated input channel still restores exact values for native machine validation. Ordinary string input CLI text is unchanged. Schema-unavailable calls retain their existing CLI behavior and child-side validation. An invalid source schedule does not block an independent manual invocation with valid business inputs.

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/lib/core/child-result.js

@@ -0,0 +1,80 @@
+// @ts-check
+// Loaded only into the owned CLI child, never into the resident application.
+const fs = require('node:fs')
+const Module = /** @type {any} */ (require('node:module'))
+const path = require('node:path')
+const { encodeResult, byteLimit } = require('./result')
+const scriptPath = process.env.QUEST_SCRIPT_PATH
+const runId = process.env.QUEST_RUN_ID
+const limit = byteLimit(Number(process.env.QUEST_RESULT_BYTES))
+
+if (scriptPath && runId) {
+  const inputs = JSON.parse(fs.readFileSync(4, 'utf8'))
+  require('./execution-child').markExecutionChild()
+  // Avoid propagating the contract to grandchildren that do not own these fds.
+  delete process.env.QUEST_SCRIPT_PATH
+  delete process.env.QUEST_RUN_ID
+  delete process.env.QUEST_RESULT_BYTES
+  const wrappedFns = new Set()
+  let sent = false
+  function capture(value, exit) {
+    if (sent) return
+    sent = true
+    const result = encodeResult(value, limit)
+    delete result.json
+    if (exit) result.exit = exit
+    const envelope = JSON.stringify({ version: 1, runId, result })
+    // Synchronous write prevents whelk's process.exit from discarding the result.
+    const buffer = Buffer.from(envelope)
+    let offset = 0
+    while (offset < buffer.length)
+      offset += fs.writeSync(3, buffer, offset, buffer.length - offset)
+  }
+  const originalLoad = Module._load
+  Module._load = function (request, parent, isMain) {
+    const exported = originalLoad.apply(this, arguments)
+    if (request === 'machine' && exported.buildWithCustomUsage) {
+      return Object.assign({}, exported, {
+        buildWithCustomUsage(options, omen) {
+          const wet = exported.buildWithCustomUsage(options, omen)
+          if (!wrappedFns.has(options.def.fn)) return wet
+          // Keep whelk lifecycle/validation but supply exact JSON values instead
+          // of letting CLI parsing turn null/false/0/string values into guesses.
+          const configured = function () {
+            const deferred = wet(inputs)
+            const originalExec = deferred.exec
+            deferred.exec = function (callback) {
+              return originalExec.call(this, function (error, result) {
+                if (!error) capture(result)
+                else if (
+                  error.name === 'Exception' &&
+                  typeof error.exit === 'string'
+                )
+                  capture(error.raw, error.exit)
+                return callback.apply(this, arguments)
+              })
+            }
+            return deferred
+          }
+          Object.setPrototypeOf(configured, wet)
+          return configured
+        }
+      })
+    }
+    if (!request.endsWith(path.basename(scriptPath))) return exported
+    let resolved
+    try {
+      resolved = Module._resolveFilename(request, parent)
+    } catch {
+      return exported
+    }
+    if (
+      resolved !== scriptPath ||
+      !exported ||
+      typeof exported.fn !== 'function'
+    )
+      return exported
+    wrappedFns.add(exported.fn)
+    return exported
+  }
+}

package/lib/core/execution-child.js

@@ -0,0 +1,14 @@
+// @ts-check
+// This state exists only in this Node process. It is never put in the child
+// environment, so an unrelated grandchild does not inherit scheduler authority.
+let executionChild = false
+
+function markExecutionChild() {
+  executionChild = true
+}
+
+function isExecutionChild() {
+  return executionChild
+}
+
+module.exports = { markExecutionChild, isExecutionChild }