@db-lyon/flowkit 0.11.2 → 0.13.0

package/dist/task/shell-termination.js

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+export const POSIX_SIGTERM_GRACE_MS = 250;
+export const POSIX_TERMINATION_GRACE_MS = 1_000;
+export const WINDOWS_TERMINATION_GRACE_MS = 3_000;
+export function terminationGraceMs(platform) {
+    return platform === 'win32' ? WINDOWS_TERMINATION_GRACE_MS : POSIX_TERMINATION_GRACE_MS;
+}
+/**
+ * Start termination for one shell invocation.
+ *
+ * This module is deliberately internal. Passing the platform and process
+ * functions as dependencies makes the policy testable on every CI platform
+ * without changing ShellTask's public API or relying on global mutable state.
+ */
+export function beginShellTermination(child, dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const spawnProcess = dependencies.spawnProcess ?? spawn;
+    const killProcessGroup = dependencies.killProcessGroup ??
+        ((pid, signal) => {
+            process.kill(pid, signal);
+        });
+    let active = true;
+    let escalated = false;
+    let rootForceRequested = false;
+    let treeKiller;
+    let treeKillerFinished = false;
+    let treeKillComplete = platform !== 'win32' || child.pid === undefined;
+    const treeKillListeners = new Set();
+    const markTreeKillComplete = () => {
+        if (treeKillComplete)
+            return;
+        treeKillComplete = true;
+        for (const listener of treeKillListeners)
+            listener();
+        treeKillListeners.clear();
+    };
+    const killRoot = (signal) => {
+        if (!active)
+            return;
+        if (signal === 'SIGKILL' && rootForceRequested)
+            return;
+        try {
+            const sent = child.kill(signal);
+            if (signal === 'SIGKILL' && sent)
+                rootForceRequested = true;
+        }
+        catch {
+            // The shell may have closed between the terminal event and this call.
+        }
+    };
+    const killGroup = (signal) => {
+        if (!active || child.pid === undefined) {
+            killRoot(signal);
+            return;
+        }
+        try {
+            killProcessGroup(-child.pid, signal);
+        }
+        catch {
+            // A missing process group or unsupported group signal falls back to the
+            // direct shell. This cannot promise termination of escaped descendants.
+            killRoot(signal);
+        }
+    };
+    const stopTreeKiller = () => {
+        if (!treeKiller || treeKillerFinished)
+            return;
+        // Retain an error handler because a forced helper close may race an error.
+        treeKiller.once('error', () => undefined);
+        try {
+            treeKiller.kill('SIGKILL');
+        }
+        catch {
+            // The helper may already be exiting.
+        }
+        try {
+            treeKiller.unref();
+        }
+        catch {
+            // Releasing the task result must not be defeated by an unref race.
+        }
+        treeKillerFinished = true;
+    };
+    if (platform === 'win32' && child.pid !== undefined) {
+        try {
+            treeKiller = spawnProcess('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+            const killOnError = () => {
+                if (!active)
+                    return;
+                killRoot('SIGKILL');
+                markTreeKillComplete();
+            };
+            treeKiller.once('error', killOnError);
+            treeKiller.once('close', (code) => {
+                if (!active)
+                    return;
+                treeKillerFinished = true;
+                if (code !== 0)
+                    killRoot('SIGKILL');
+                markTreeKillComplete();
+            });
+        }
+        catch {
+            killRoot('SIGKILL');
+            markTreeKillComplete();
+        }
+    }
+    else {
+        // Cooperative first phase. ShellTask schedules the bounded SIGKILL
+        // escalation so normal commands can flush and clean up.
+        killGroup('SIGTERM');
+    }
+    const escalate = () => {
+        if (!active || escalated)
+            return;
+        escalated = true;
+        if (platform === 'win32') {
+            killRoot('SIGKILL');
+            stopTreeKiller();
+            return;
+        }
+        killGroup('SIGKILL');
+    };
+    const dispose = () => {
+        if (!active)
+            return;
+        treeKillListeners.clear();
+        try {
+            stopTreeKiller();
+        }
+        finally {
+            active = false;
+        }
+    };
+    const release = () => {
+        if (!active)
+            return;
+        treeKillListeners.clear();
+        escalate();
+        try {
+            child.stdout?.destroy();
+        }
+        catch {
+            // The stream may have closed between escalation and release.
+        }
+        try {
+            child.stderr?.destroy();
+        }
+        catch {
+            // The stream may have closed between escalation and release.
+        }
+        try {
+            child.unref();
+        }
+        catch {
+            // A bounded result still settles if Node rejects an unref race.
+        }
+        try {
+            stopTreeKiller();
+        }
+        finally {
+            active = false;
+        }
+    };
+    return {
+        platform,
+        isTreeKillComplete: () => treeKillComplete,
+        onTreeKillComplete: (listener) => {
+            if (treeKillComplete)
+                listener();
+            else
+                treeKillListeners.add(listener);
+        },
+        escalate,
+        release,
+        dispose,
+    };
+}
+//# sourceMappingURL=shell-termination.js.map

package/dist/task/shell-termination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-termination.js","sourceRoot":"","sources":["../../src/task/shell-termination.ts"],"names":[],"mappings":"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"}

package/dist/task/task-resolution.d.ts

@@ -0,0 +1,33 @@
+import type { TaskDefinition } from '../config/schema.js';
+import { type ReferenceContext } from '../references.js';
+/**
+ * A configured task name resolved to the class the registry loads and the
+ * options it is instantiated with.
+ */
+export interface ResolvedTask {
+    classPath: string;
+    options: Record<string, unknown>;
+}
+/**
+ * Resolve a configured task name to its class path and default options.
+ *
+ * An option-only entry (no `class_path`) layers options onto a base of the same
+ * name; absent a base class_path, it resolves by the task name itself. A name
+ * with no definition at all resolves to itself, so a bare class path still
+ * works outside — or alongside — a configuration.
+ */
+export declare function resolveTaskDefinition(taskName: string, taskDefinitions?: Record<string, TaskDefinition>): ResolvedTask;
+/**
+ * Resolve a call to a configured task: its class path, plus call-time `options`
+ * layered over the task's configured defaults.
+ *
+ * `references` interpolates `${ns.path}` in the **configured defaults only**.
+ * `options` are runtime data — a rollback payload, an agent's tool arguments,
+ * values one task computed for another — and are merged in verbatim, so a
+ * literal `${steps.x}` in runtime data reaches the task unchanged rather than
+ * being interpreted as configuration (or throwing, out of a step's scope).
+ * Callers whose call-time options *are* configuration resolve them themselves
+ * before calling; see `FlowRunner.runTask`.
+ */
+export declare function resolveTaskCall(taskName: string, taskDefinitions: Record<string, TaskDefinition> | undefined, options?: Record<string, unknown>, references?: ReferenceContext): ResolvedTask;
+//# sourceMappingURL=task-resolution.d.ts.map

package/dist/task/task-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-resolution.d.ts","sourceRoot":"","sources":["../../src/task/task-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE5E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAC/C,YAAY,CAMd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EAC3D,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACrC,UAAU,CAAC,EAAE,gBAAgB,GAC5B,YAAY,CAId"}

package/dist/task/task-resolution.js

@@ -0,0 +1,34 @@
+import { resolveReferences } from '../references.js';
+/**
+ * Resolve a configured task name to its class path and default options.
+ *
+ * An option-only entry (no `class_path`) layers options onto a base of the same
+ * name; absent a base class_path, it resolves by the task name itself. A name
+ * with no definition at all resolves to itself, so a bare class path still
+ * works outside — or alongside — a configuration.
+ */
+export function resolveTaskDefinition(taskName, taskDefinitions) {
+    const def = taskDefinitions?.[taskName];
+    return {
+        classPath: def?.class_path ?? taskName,
+        options: def?.options ?? {},
+    };
+}
+/**
+ * Resolve a call to a configured task: its class path, plus call-time `options`
+ * layered over the task's configured defaults.
+ *
+ * `references` interpolates `${ns.path}` in the **configured defaults only**.
+ * `options` are runtime data — a rollback payload, an agent's tool arguments,
+ * values one task computed for another — and are merged in verbatim, so a
+ * literal `${steps.x}` in runtime data reaches the task unchanged rather than
+ * being interpreted as configuration (or throwing, out of a step's scope).
+ * Callers whose call-time options *are* configuration resolve them themselves
+ * before calling; see `FlowRunner.runTask`.
+ */
+export function resolveTaskCall(taskName, taskDefinitions, options = {}, references) {
+    const def = resolveTaskDefinition(taskName, taskDefinitions);
+    const defaults = references ? resolveReferences(def.options, references) : def.options;
+    return { classPath: def.classPath, options: { ...defaults, ...options } };
+}
+//# sourceMappingURL=task-resolution.js.map

package/dist/task/task-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-resolution.js","sourceRoot":"","sources":["../../src/task/task-resolution.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAyB,MAAM,kBAAkB,CAAC;AAW5E;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,eAAgD;IAEhD,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC,QAAQ,CAAC,CAAC;IACxC,OAAO;QACL,SAAS,EAAE,GAAG,EAAE,UAAU,IAAI,QAAQ;QACtC,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,eAA2D,EAC3D,UAAmC,EAAE,EACrC,UAA6B;IAE7B,MAAM,GAAG,GAAG,qBAAqB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;IACvF,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,EAAE,EAAE,CAAC;AAC5E,CAAC"}