@blokjs/runner 0.2.0

package/dist/RuntimeAdapterNode.d.ts

@@ -0,0 +1,19 @@
+import type { Context, ResponseContext } from "@blokjs/shared";
+import RunnerNode from "./RunnerNode";
+import type { RuntimeAdapter } from "./adapters/RuntimeAdapter";
+/**
+ * RuntimeAdapterNode is a wrapper that bridges the existing RunnerNode interface
+ * with the new RuntimeAdapter system.
+ *
+ * This allows runtime adapters to be used seamlessly within the existing
+ * workflow execution engine without breaking changes.
+ */
+export declare class RuntimeAdapterNode extends RunnerNode {
+    private adapter;
+    private targetNode;
+    constructor(adapter: RuntimeAdapter, targetNode: RunnerNode);
+    /**
+     * Execute the node using the runtime adapter
+     */
+    run(ctx: Context): Promise<ResponseContext>;
+}

package/dist/RuntimeAdapterNode.js

@@ -0,0 +1,87 @@
+import { GlobalError } from "@blokjs/shared";
+import RunnerNode from "./RunnerNode";
+import { RunTracker } from "./tracing/RunTracker";
+/**
+ * RuntimeAdapterNode is a wrapper that bridges the existing RunnerNode interface
+ * with the new RuntimeAdapter system.
+ *
+ * This allows runtime adapters to be used seamlessly within the existing
+ * workflow execution engine without breaking changes.
+ */
+export class RuntimeAdapterNode extends RunnerNode {
+    adapter;
+    targetNode;
+    constructor(adapter, targetNode) {
+        super();
+        this.adapter = adapter;
+        this.targetNode = targetNode;
+        // Copy properties from target node
+        this.node = targetNode.node;
+        this.name = targetNode.name;
+        this.type = targetNode.type;
+        this.runtime = targetNode.runtime;
+        this.active = targetNode.active;
+        this.stop = targetNode.stop;
+        this.set_var = targetNode.set_var;
+    }
+    /**
+     * Execute the node using the runtime adapter
+     */
+    async run(ctx) {
+        const result = await this.adapter.execute(this.targetNode, ctx);
+        // --- Trace: capture runtime metrics ---
+        const traceNodeId = ctx._traceNodeId;
+        if (traceNodeId && result.metrics) {
+            const tracker = RunTracker.getInstance();
+            const nodeRun = tracker.getNodeRun(traceNodeId);
+            if (nodeRun) {
+                nodeRun.metrics = {
+                    duration_ms: result.metrics.duration_ms,
+                    cpu_ms: result.metrics.cpu_ms,
+                    memory_bytes: result.metrics.memory_bytes,
+                };
+                nodeRun.runtimeKind = this.adapter.kind;
+            }
+        }
+        // Ensure ctx.vars exists
+        if (!ctx.vars) {
+            ctx.vars = {};
+        }
+        const vars = ctx.vars;
+        // Merge SDK-returned vars into ctx.vars (if the SDK server includes them)
+        if (result.vars && typeof result.vars === "object") {
+            Object.assign(vars, result.vars);
+        }
+        // Auto-save the step's result data into ctx.vars[stepName]
+        // This ensures each runtime step's output is accessible downstream,
+        // even if the SDK server doesn't explicitly return vars
+        if (result.data != null) {
+            vars[this.name] = result.data;
+        }
+        // Convert errors to GlobalError if present
+        let error = null;
+        if (result.errors) {
+            if (result.errors instanceof GlobalError) {
+                error = result.errors;
+            }
+            else if (typeof result.errors === "object" && result.errors !== null) {
+                const err = result.errors;
+                error = new GlobalError(err.message || "Runtime execution error");
+                if (err.stack)
+                    error.setStack(err.stack);
+                if (err.name)
+                    error.setName(err.name);
+            }
+            else {
+                error = new GlobalError(String(result.errors));
+            }
+        }
+        // Convert ExecutionResult to ResponseContext
+        return {
+            success: result.success,
+            data: result.data,
+            error,
+        };
+    }
+}
+//# sourceMappingURL=RuntimeAdapterNode.js.map

package/dist/RuntimeAdapterNode.js.map

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

package/dist/RuntimeRegistry.d.ts

@@ -0,0 +1,61 @@
+import type { RuntimeAdapter, RuntimeKind } from "./adapters/RuntimeAdapter";
+/**
+ * RuntimeRegistry is a singleton that manages all runtime adapters
+ *
+ * Usage:
+ * ```typescript
+ * const registry = RuntimeRegistry.getInstance();
+ * registry.register(new NodeJsRuntimeAdapter());
+ * registry.register(new HttpRuntimeAdapter("python3", "localhost", 9007));
+ *
+ * const adapter = registry.get("nodejs");
+ * const result = await adapter.execute(node, ctx);
+ * ```
+ */
+export declare class RuntimeRegistry {
+    private static instance;
+    private adapters;
+    private constructor();
+    /**
+     * Get the singleton instance of RuntimeRegistry
+     */
+    static getInstance(): RuntimeRegistry;
+    /**
+     * Register a runtime adapter
+     *
+     * @param adapter - The runtime adapter to register
+     * @throws Error if adapter with same kind is already registered
+     */
+    register(adapter: RuntimeAdapter): void;
+    /**
+     * Get a runtime adapter by kind
+     *
+     * @param kind - The runtime kind (nodejs, python3, go, etc.)
+     * @returns The runtime adapter for the specified kind
+     * @throws Error if no adapter is registered for the specified kind
+     */
+    get(kind: RuntimeKind): RuntimeAdapter;
+    /**
+     * Check if a runtime adapter is registered
+     *
+     * @param kind - The runtime kind to check
+     * @returns true if adapter is registered, false otherwise
+     */
+    has(kind: RuntimeKind): boolean;
+    /**
+     * Get all registered runtime kinds
+     *
+     * @returns Array of registered runtime kinds
+     */
+    getRegisteredKinds(): RuntimeKind[];
+    /**
+     * Clear all registered adapters (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Replace an existing adapter (useful for testing or hot-reload)
+     *
+     * @param adapter - The runtime adapter to replace
+     */
+    replace(adapter: RuntimeAdapter): void;
+}

package/dist/RuntimeRegistry.js

@@ -0,0 +1,87 @@
+/**
+ * RuntimeRegistry is a singleton that manages all runtime adapters
+ *
+ * Usage:
+ * ```typescript
+ * const registry = RuntimeRegistry.getInstance();
+ * registry.register(new NodeJsRuntimeAdapter());
+ * registry.register(new HttpRuntimeAdapter("python3", "localhost", 9007));
+ *
+ * const adapter = registry.get("nodejs");
+ * const result = await adapter.execute(node, ctx);
+ * ```
+ */
+export class RuntimeRegistry {
+    static instance;
+    adapters;
+    constructor() {
+        this.adapters = new Map();
+    }
+    /**
+     * Get the singleton instance of RuntimeRegistry
+     */
+    static getInstance() {
+        if (!RuntimeRegistry.instance) {
+            RuntimeRegistry.instance = new RuntimeRegistry();
+        }
+        return RuntimeRegistry.instance;
+    }
+    /**
+     * Register a runtime adapter
+     *
+     * @param adapter - The runtime adapter to register
+     * @throws Error if adapter with same kind is already registered
+     */
+    register(adapter) {
+        if (this.adapters.has(adapter.kind)) {
+            throw new Error(`Runtime adapter for '${adapter.kind}' is already registered`);
+        }
+        this.adapters.set(adapter.kind, adapter);
+    }
+    /**
+     * Get a runtime adapter by kind
+     *
+     * @param kind - The runtime kind (nodejs, python3, go, etc.)
+     * @returns The runtime adapter for the specified kind
+     * @throws Error if no adapter is registered for the specified kind
+     */
+    get(kind) {
+        const adapter = this.adapters.get(kind);
+        if (!adapter) {
+            throw new Error(`No runtime adapter registered for '${kind}'. Available runtimes: ${Array.from(this.adapters.keys()).join(", ")}`);
+        }
+        return adapter;
+    }
+    /**
+     * Check if a runtime adapter is registered
+     *
+     * @param kind - The runtime kind to check
+     * @returns true if adapter is registered, false otherwise
+     */
+    has(kind) {
+        return this.adapters.has(kind);
+    }
+    /**
+     * Get all registered runtime kinds
+     *
+     * @returns Array of registered runtime kinds
+     */
+    getRegisteredKinds() {
+        return Array.from(this.adapters.keys());
+    }
+    /**
+     * Clear all registered adapters (useful for testing)
+     */
+    clear() {
+        this.adapters.clear();
+    }
+    /**
+     * Replace an existing adapter (useful for testing or hot-reload)
+     *
+     * @param adapter - The runtime adapter to replace
+     */
+    replace(adapter) {
+        this.adapters.set(adapter.kind, adapter);
+    }
+}
+//# sourceMappingURL=RuntimeRegistry.js.map

package/dist/RuntimeRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeRegistry.js","sourceRoot":"","sources":["../src/RuntimeRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAe;IACnB,MAAM,CAAC,QAAQ,CAAkB;IACjC,QAAQ,CAAmC;IAEnD;QACC,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAC;IACxD,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,WAAW;QACxB,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC;YAC/B,eAAe,CAAC,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;QAClD,CAAC;QACD,OAAO,eAAe,CAAC,QAAQ,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACI,QAAQ,CAAC,OAAuB;QACtC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,CAAC,IAAI,yBAAyB,CAAC,CAAC;QAChF,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;OAMG;IACI,GAAG,CAAC,IAAiB;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACd,sCAAsC,IAAI,0BAA0B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACjH,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAC,IAAiB;QAC3B,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACI,kBAAkB;QACxB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACI,KAAK;QACX,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,OAAuB;QACrC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;CACD"}

package/dist/TriggerBase.d.ts

@@ -0,0 +1,119 @@
+import { type Context, type LoggerContext, Trigger } from "@blokjs/shared";
+import Configuration from "./Configuration";
+import Runner from "./Runner";
+import type { HMREvent } from "./hmr/FileWatcher";
+import { HotReloadManager, type HotReloadManagerConfig, type HotReloadStats } from "./hmr/HotReloadManager";
+import { CircuitBreaker } from "./monitoring/CircuitBreaker";
+import type { CircuitBreakerConfig } from "./monitoring/CircuitBreaker";
+import { HealthCheck } from "./monitoring/HealthCheck";
+import type { DependencyCheckFn } from "./monitoring/HealthCheck";
+import { PrometheusMetricsBridge } from "./monitoring/PrometheusMetricsBridge";
+import { RateLimiter } from "./monitoring/RateLimiter";
+import type { RateLimitConfig, RateLimitResult } from "./monitoring/RateLimiter";
+import { TriggerMetricsCollector } from "./monitoring/TriggerMetricsCollector";
+import type TriggerResponse from "./types/TriggerResponse";
+export default abstract class TriggerBase extends Trigger {
+    configuration: Configuration;
+    /** Health check instance for this trigger */
+    protected healthCheck: HealthCheck;
+    /** Rate limiter instance - null if rate limiting is disabled */
+    protected rateLimiter: RateLimiter | null;
+    /** Circuit breaker instance - null if circuit breaker is disabled */
+    protected circuitBreaker: CircuitBreaker | null;
+    /** Enhanced metrics collector */
+    protected metricsCollector: TriggerMetricsCollector;
+    /** Prometheus metrics bridge for exporting to /metrics */
+    protected metricsBridge: PrometheusMetricsBridge;
+    /** Hot reload manager - null if HMR is disabled */
+    protected hmr: HotReloadManager | null;
+    /** Number of currently in-flight requests (for zero-downtime reload) */
+    protected inFlightRequests: number;
+    constructor();
+    abstract listen(): Promise<number>;
+    getConfiguration(): Configuration;
+    getRunner(): Runner;
+    /**
+     * Enable hot reload for this trigger. Only active in development
+     * (NODE_ENV !== 'production') unless BLOK_HMR=true is explicitly set.
+     */
+    enableHotReload(config?: Partial<HotReloadManagerConfig>): Promise<void>;
+    /**
+     * Called when a node file changes. Default: invalidates module cache.
+     * Override in subclasses for custom behavior (e.g., re-running loadNodes).
+     */
+    protected onHmrNodeChange(event: HMREvent): Promise<void>;
+    /**
+     * Called when a workflow file changes. Default: no-op.
+     * HTTP trigger re-reads per request so needs no action.
+     * Non-HTTP triggers should override to reload workflow lists.
+     */
+    protected onHmrWorkflowChange(_event: HMREvent): Promise<void>;
+    /**
+     * Called when a trigger config file changes. Default: no-op.
+     * Override for graceful stop + restart behavior.
+     */
+    protected onHmrTriggerChange(_event: HMREvent): Promise<void>;
+    /**
+     * Wait for all in-flight requests to complete before proceeding.
+     * Used during graceful reload to avoid dropping connections.
+     */
+    protected waitForInFlightRequests(timeoutMs?: number): Promise<void>;
+    /**
+     * Get HMR statistics. Returns null if HMR is not enabled.
+     */
+    getHmrStats(): HotReloadStats | null;
+    /**
+     * Stop the HMR system and clean up watchers.
+     */
+    destroyHmr(): Promise<void>;
+    run(ctx: Context): Promise<TriggerResponse>;
+    /**
+     * Build a human-readable trigger summary for trace display.
+     */
+    protected buildTraceTriggerSummary(ctx: Context): string;
+    createContext(logger?: LoggerContext, blueprintPath?: string, id?: string): Context;
+    startCounter(): number;
+    endCounter(start: number): number;
+    /**
+     * Enable rate limiting for this trigger.
+     */
+    enableRateLimiting(config: RateLimitConfig): void;
+    /**
+     * Check rate limit for a given key. Returns the result without blocking.
+     */
+    checkRateLimit(key: string): RateLimitResult;
+    /**
+     * Enable circuit breaker for this trigger.
+     */
+    enableCircuitBreaker(config: CircuitBreakerConfig): void;
+    /**
+     * Register a dependency health check (e.g., database, queue broker).
+     */
+    registerHealthDependency(name: string, checkFn: DependencyCheckFn): void;
+    /**
+     * Get full health status including all dependencies.
+     */
+    getHealth(): Promise<import(".").HealthCheckResult>;
+    /**
+     * Get liveness probe result.
+     */
+    getLiveness(): {
+        status: "ok";
+        uptime: number;
+    };
+    /**
+     * Get readiness probe result.
+     */
+    getReadiness(): Promise<{
+        ready: boolean;
+        status: import(".").HealthStatus;
+    }>;
+    /**
+     * Get enhanced trigger metrics snapshot.
+     */
+    getTriggerMetrics(): import(".").TriggerMetrics;
+    /**
+     * Clean up monitoring resources on shutdown.
+     */
+    destroyMonitoring(): void;
+}