@tasker-systems/tasker 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,118 @@
+# @tasker-systems/tasker
+
+TypeScript worker for the Tasker workflow orchestration system. Supports Bun (native FFI), Node.js (via koffi), and Deno runtimes.
+
+## Status
+
+Production ready. TypeScript worker bindings provide full step handler execution via FFI to the shared Rust `tasker-worker` infrastructure.
+
+## Installation
+
+```bash
+# Bun (recommended - native FFI support)
+bun add @tasker-systems/tasker
+
+# Node.js (requires koffi for FFI)
+npm install @tasker-systems/tasker koffi
+```
+
+## Quick Start
+
+```typescript
+import { TaskerWorker } from "@tasker-systems/tasker";
+
+const worker = new TaskerWorker({
+  workerName: "my-worker",
+  namespaces: ["default"],
+});
+
+// Register a step handler
+worker.registerHandler("process_payment", async (step) => {
+  const result = await processPayment(step.context);
+  return { status: "complete", data: result };
+});
+
+// Start the worker
+await worker.start();
+```
+
+## Development
+
+### Prerequisites
+
+- Bun 1.0+ (recommended) or Node.js 18+
+- Rust 1.70+ (for building the FFI library)
+
+### Setup
+
+```bash
+# Install dependencies
+bun install
+
+# Build TypeScript
+bun run build
+
+# Run tests
+bun test
+
+# Type checking
+bun run typecheck
+
+# Linting
+bun run check
+```
+
+### Building the FFI Library
+
+```bash
+# Build the Rust FFI shared library
+cargo build --release -p tasker-worker-ts
+
+# The library will be at target/release/libtasker_worker_ts.{dylib,so,dll}
+```
+
+## Project Structure
+
+```
+workers/typescript/
+├── src/                  # TypeScript source
+│   ├── bootstrap/        # Worker initialization
+│   ├── events/           # Event system integration
+│   ├── ffi/              # FFI bindings to Rust
+│   ├── handler/          # Step handler base classes
+│   ├── logging/          # Structured logging (pino)
+│   ├── registry/         # Handler registry
+│   ├── server/           # HTTP/gRPC server
+│   ├── subscriber/       # Queue subscriber
+│   ├── types/            # Type definitions
+│   └── index.ts          # Package entry point
+├── src-rust/             # Rust FFI source
+│   └── lib.rs            # Neon/FFI module
+├── tests/                # Test suite
+├── Cargo.toml            # Rust crate configuration
+├── package.json          # npm package configuration
+├── tsconfig.json         # TypeScript configuration
+└── biome.json            # Linting configuration
+```
+
+## Technology Stack
+
+- **FFI Layer**: Bun native FFI / koffi (Node.js)
+- **Build Tool**: tsup
+- **Runtime**: Bun, Node.js 18+, or Deno
+- **Testing**: Bun test runner
+- **Linting**: Biome
+- **Logging**: pino
+- **Events**: eventemitter3
+
+## Runtime Support
+
+| Runtime | FFI Mechanism | Status |
+|---------|---------------|--------|
+| Bun | Native `bun:ffi` | Recommended |
+| Node.js | koffi | Supported |
+| Deno | `Deno.dlopen` | Experimental |
+
+## License
+
+MIT

package/dist/events/index.d.ts

@@ -1,3 +1,3 @@
-export { y as ErrorCallback, n as EventName, o as EventNames, d as EventPoller, z as EventPollerConfig, f as EventSystem, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, T as TaskerEventEmitter, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller } from '../index-B3BcknlZ.js';
+export { y as ErrorCallback, n as EventName, o as EventNames, d as EventPoller, z as EventPollerConfig, f as EventSystem, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, T as TaskerEventEmitter, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller } from '../index-CTl8lGpU.js';
 import 'eventemitter3';
-import '../runtime-interface-CE4viUt7.js';
+import '../runtime-interface-D940vUzy.js';

package/dist/ffi/index.d.ts

@@ -1,139 +1,5 @@
-import { B as BaseTaskerRuntime, a as BootstrapConfig, b as BootstrapResult, W as WorkerStatus, q as StopResult, l as FfiStepEvent, F as FfiDomainEvent, p as StepExecutionResult, t as CheckpointYieldData, k as FfiDispatchMetrics, L as LogFields, d as ClientResult, T as TaskerRuntime } from '../runtime-interface-CE4viUt7.js';
-export { D as DependencyResult, u as FfiDomainEventMetadata, m as HandlerDefinition, O as OrchestrationMetadata, R as RetryConfiguration, S as StepDefinition, n as StepExecutionError, o as StepExecutionMetadata, r as Task, s as WorkflowStep } from '../runtime-interface-CE4viUt7.js';
-
-/**
- * Node.js FFI runtime adapter using koffi.
- *
- * This adapter uses the koffi package to interface with the Rust native library.
- * Koffi is a modern, actively maintained FFI library with prebuilt binaries.
- *
- * Install: npm install koffi
- */
-
-/**
- * Node.js FFI runtime implementation using koffi
- */
-declare class NodeRuntime extends BaseTaskerRuntime {
-    readonly name: string;
-    private lib;
-    private koffi;
-    get isLoaded(): boolean;
-    load(libraryPath: string): Promise<void>;
-    unload(): void;
-    private ensureLoaded;
-    /**
-     * Read a C string from a pointer and free the Rust-allocated memory.
-     *
-     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
-     */
-    private readAndFreeRustString;
-    getVersion(): string;
-    getRustVersion(): string;
-    healthCheck(): boolean;
-    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
-    isWorkerRunning(): boolean;
-    getWorkerStatus(): WorkerStatus;
-    stopWorker(): StopResult;
-    transitionToGracefulShutdown(): StopResult;
-    pollStepEvents(): FfiStepEvent | null;
-    pollInProcessEvents(): FfiDomainEvent | null;
-    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
-    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
-    getFfiDispatchMetrics(): FfiDispatchMetrics;
-    checkStarvationWarnings(): void;
-    cleanupTimeouts(): void;
-    logError(message: string, fields?: LogFields): void;
-    logWarn(message: string, fields?: LogFields): void;
-    logInfo(message: string, fields?: LogFields): void;
-    logDebug(message: string, fields?: LogFields): void;
-    logTrace(message: string, fields?: LogFields): void;
-    private parseClientResult;
-    clientCreateTask(requestJson: string): ClientResult;
-    clientGetTask(taskUuid: string): ClientResult;
-    clientListTasks(paramsJson: string): ClientResult;
-    clientCancelTask(taskUuid: string): ClientResult;
-    clientListTaskSteps(taskUuid: string): ClientResult;
-    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
-    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
-    clientHealthCheck(): ClientResult;
-}
-
-/**
- * Bun FFI runtime adapter using koffi (via Node-API).
- *
- * Bun supports Node-API modules natively, so we use koffi (the same FFI
- * library as NodeRuntime) rather than bun:ffi. This gives us:
- * - Stable, well-tested string/pointer handling
- * - Identical behavior across Node.js and Bun
- * - No manual Buffer→pointer conversion bugs
- *
- * See: https://bun.sh/docs/runtime/node-api
- */
-
-/**
- * Bun FFI runtime implementation using koffi (Node-API).
- *
- * Extends NodeRuntime since both use koffi for FFI. The only difference
- * is the runtime name identifier used for logging and diagnostics.
- */
-declare class BunRuntime extends NodeRuntime {
-    readonly name = "bun";
-}
-
-/**
- * Deno FFI runtime adapter using Deno.dlopen.
- *
- * This adapter uses Deno's built-in FFI to interface with the Rust native library.
- * It requires --unstable-ffi and --allow-ffi flags.
- */
-
-/**
- * Deno FFI runtime implementation using Deno.dlopen
- */
-declare class DenoRuntime extends BaseTaskerRuntime {
-    readonly name = "deno";
-    private lib;
-    private encoder;
-    get isLoaded(): boolean;
-    load(libraryPath: string): Promise<void>;
-    unload(): void;
-    private ensureLoaded;
-    /**
-     * Creates a null-terminated C string buffer.
-     * With 'buffer' FFI type, we return Uint8Array directly.
-     */
-    private toCString;
-    private fromCString;
-    getVersion(): string;
-    getRustVersion(): string;
-    healthCheck(): boolean;
-    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
-    isWorkerRunning(): boolean;
-    getWorkerStatus(): WorkerStatus;
-    stopWorker(): StopResult;
-    transitionToGracefulShutdown(): StopResult;
-    pollStepEvents(): FfiStepEvent | null;
-    pollInProcessEvents(): FfiDomainEvent | null;
-    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
-    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
-    getFfiDispatchMetrics(): FfiDispatchMetrics;
-    checkStarvationWarnings(): void;
-    cleanupTimeouts(): void;
-    logError(message: string, fields?: LogFields): void;
-    logWarn(message: string, fields?: LogFields): void;
-    logInfo(message: string, fields?: LogFields): void;
-    logDebug(message: string, fields?: LogFields): void;
-    logTrace(message: string, fields?: LogFields): void;
-    private parseClientResult;
-    clientCreateTask(requestJson: string): ClientResult;
-    clientGetTask(taskUuid: string): ClientResult;
-    clientListTasks(paramsJson: string): ClientResult;
-    clientCancelTask(taskUuid: string): ClientResult;
-    clientListTaskSteps(taskUuid: string): ClientResult;
-    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
-    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
-    clientHealthCheck(): ClientResult;
-}
+import { T as TaskerRuntime, B as BaseTaskerRuntime, e as BootstrapConfig, f as BootstrapResult, W as WorkerStatus, q as StopResult, l as FfiStepEvent, F as FfiDomainEvent, p as StepExecutionResult, t as CheckpointYieldData, k as FfiDispatchMetrics, L as LogFields, h as ClientResult } from '../runtime-interface-D940vUzy.js';
+export { D as DependencyResult, u as FfiDomainEventMetadata, m as HandlerDefinition, O as OrchestrationMetadata, R as RetryConfiguration, S as StepDefinition, n as StepExecutionError, o as StepExecutionMetadata, r as Task, s as WorkflowStep } from '../runtime-interface-D940vUzy.js';
 
 /**
  * Runtime detection for TypeScript/JavaScript workers.
@@ -280,9 +146,9 @@ declare class FfiLayer {
      * Static method for finding the library path without creating an instance.
      * Useful for test utilities and pre-flight checks.
      *
-     * REQUIRES: TASKER_FFI_LIBRARY_PATH environment variable to be set.
-     * This explicit requirement prevents confusion from automatic debug/release
-     * library discovery and ensures intentional configuration at build/runtime.
+     * Resolution order:
+     * 1. TASKER_FFI_LIBRARY_PATH environment variable (explicit override)
+     * 2. Bundled native library in the package's native/ directory
      *
      * @param _callerDir Deprecated parameter, kept for API compatibility
      * @returns Path to the library if found and exists, null otherwise
@@ -305,4 +171,138 @@ declare class FfiLayer {
     private createRuntime;
 }
 
+/**
+ * Node.js FFI runtime adapter using koffi.
+ *
+ * This adapter uses the koffi package to interface with the Rust native library.
+ * Koffi is a modern, actively maintained FFI library with prebuilt binaries.
+ *
+ * Install: npm install koffi
+ */
+
+/**
+ * Node.js FFI runtime implementation using koffi
+ */
+declare class NodeRuntime extends BaseTaskerRuntime {
+    readonly name: string;
+    private lib;
+    private koffi;
+    get isLoaded(): boolean;
+    load(libraryPath: string): Promise<void>;
+    unload(): void;
+    private ensureLoaded;
+    /**
+     * Read a C string from a pointer and free the Rust-allocated memory.
+     *
+     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
+     */
+    private readAndFreeRustString;
+    getVersion(): string;
+    getRustVersion(): string;
+    healthCheck(): boolean;
+    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
+    isWorkerRunning(): boolean;
+    getWorkerStatus(): WorkerStatus;
+    stopWorker(): StopResult;
+    transitionToGracefulShutdown(): StopResult;
+    pollStepEvents(): FfiStepEvent | null;
+    pollInProcessEvents(): FfiDomainEvent | null;
+    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
+    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
+    getFfiDispatchMetrics(): FfiDispatchMetrics;
+    checkStarvationWarnings(): void;
+    cleanupTimeouts(): void;
+    logError(message: string, fields?: LogFields): void;
+    logWarn(message: string, fields?: LogFields): void;
+    logInfo(message: string, fields?: LogFields): void;
+    logDebug(message: string, fields?: LogFields): void;
+    logTrace(message: string, fields?: LogFields): void;
+    private parseClientResult;
+    clientCreateTask(requestJson: string): ClientResult;
+    clientGetTask(taskUuid: string): ClientResult;
+    clientListTasks(paramsJson: string): ClientResult;
+    clientCancelTask(taskUuid: string): ClientResult;
+    clientListTaskSteps(taskUuid: string): ClientResult;
+    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
+    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
+    clientHealthCheck(): ClientResult;
+}
+
+/**
+ * Bun FFI runtime adapter using koffi (via Node-API).
+ *
+ * Bun supports Node-API modules natively, so we use koffi (the same FFI
+ * library as NodeRuntime) rather than bun:ffi. This gives us:
+ * - Stable, well-tested string/pointer handling
+ * - Identical behavior across Node.js and Bun
+ * - No manual Buffer→pointer conversion bugs
+ *
+ * See: https://bun.sh/docs/runtime/node-api
+ */
+
+/**
+ * Bun FFI runtime implementation using koffi (Node-API).
+ *
+ * Extends NodeRuntime since both use koffi for FFI. The only difference
+ * is the runtime name identifier used for logging and diagnostics.
+ */
+declare class BunRuntime extends NodeRuntime {
+    readonly name = "bun";
+}
+
+/**
+ * Deno FFI runtime adapter using Deno.dlopen.
+ *
+ * This adapter uses Deno's built-in FFI to interface with the Rust native library.
+ * It requires --unstable-ffi and --allow-ffi flags.
+ */
+
+/**
+ * Deno FFI runtime implementation using Deno.dlopen
+ */
+declare class DenoRuntime extends BaseTaskerRuntime {
+    readonly name = "deno";
+    private lib;
+    private encoder;
+    get isLoaded(): boolean;
+    load(libraryPath: string): Promise<void>;
+    unload(): void;
+    private ensureLoaded;
+    /**
+     * Creates a null-terminated C string buffer.
+     * With 'buffer' FFI type, we return Uint8Array directly.
+     */
+    private toCString;
+    private fromCString;
+    getVersion(): string;
+    getRustVersion(): string;
+    healthCheck(): boolean;
+    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
+    isWorkerRunning(): boolean;
+    getWorkerStatus(): WorkerStatus;
+    stopWorker(): StopResult;
+    transitionToGracefulShutdown(): StopResult;
+    pollStepEvents(): FfiStepEvent | null;
+    pollInProcessEvents(): FfiDomainEvent | null;
+    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
+    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
+    getFfiDispatchMetrics(): FfiDispatchMetrics;
+    checkStarvationWarnings(): void;
+    cleanupTimeouts(): void;
+    logError(message: string, fields?: LogFields): void;
+    logWarn(message: string, fields?: LogFields): void;
+    logInfo(message: string, fields?: LogFields): void;
+    logDebug(message: string, fields?: LogFields): void;
+    logTrace(message: string, fields?: LogFields): void;
+    private parseClientResult;
+    clientCreateTask(requestJson: string): ClientResult;
+    clientGetTask(taskUuid: string): ClientResult;
+    clientListTasks(paramsJson: string): ClientResult;
+    clientCancelTask(taskUuid: string): ClientResult;
+    clientListTaskSteps(taskUuid: string): ClientResult;
+    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
+    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
+    clientHealthCheck(): ClientResult;
+}
+
 export { BaseTaskerRuntime, BootstrapConfig, BootstrapResult, BunRuntime, DenoRuntime, FfiDispatchMetrics, FfiDomainEvent, FfiLayer, type FfiLayerConfig, FfiStepEvent, LogFields, NodeRuntime, type RuntimeInfo, type RuntimeType, StepExecutionResult, StopResult, TaskerRuntime, WorkerStatus, detectRuntime, getLibraryPath, getRuntimeInfo, isBun, isDeno, isNode };

package/dist/ffi/index.js

@@ -1,4 +1,6 @@
 import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -517,8 +519,8 @@ var require_koffi19 = __commonJS2({
                   data = data.subarray(0, header.size);
                   if (header.type == "0" || header.type == "7") {
                     let filename3 = dest_dir + "/" + header.filename;
-                    let dirname = path2.dirname(filename3);
-                    fs2.mkdirSync(dirname, { recursive: true, mode: 493 });
+                    let dirname2 = path2.dirname(filename3);
+                    fs2.mkdirSync(dirname2, { recursive: true, mode: 493 });
                     fs2.writeFileSync(filename3, data, { mode: header.mode });
                   } else if (header.type == "5") {
                     let filename3 = dest_dir + "/" + header.filename;
@@ -1829,7 +1831,10 @@ var FfiLayer = class _FfiLayer {
     const path2 = customPath ?? this.configuredLibraryPath ?? this.discoverLibraryPath();
     if (!path2) {
       throw new Error(
-        "FFI library not found. TASKER_FFI_LIBRARY_PATH environment variable must be set to the path of the compiled library.\nExample: export TASKER_FFI_LIBRARY_PATH=/path/to/target/debug/libtasker_ts.dylib\nBuild the library with: cargo build -p tasker-ts"
+        `FFI library not found. No bundled native library matches this platform, and TASKER_FFI_LIBRARY_PATH is not set.
+Current platform: ${process.platform}-${process.arch}
+Supported: linux-x64, linux-arm64, darwin-arm64
+Override: export TASKER_FFI_LIBRARY_PATH=/path/to/libtasker_ts.dylib`
       );
     }
     this.runtime = await this.createRuntime();
@@ -1883,23 +1888,27 @@ var FfiLayer = class _FfiLayer {
    * Static method for finding the library path without creating an instance.
    * Useful for test utilities and pre-flight checks.
    *
-   * REQUIRES: TASKER_FFI_LIBRARY_PATH environment variable to be set.
-   * This explicit requirement prevents confusion from automatic debug/release
-   * library discovery and ensures intentional configuration at build/runtime.
+   * Resolution order:
+   * 1. TASKER_FFI_LIBRARY_PATH environment variable (explicit override)
+   * 2. Bundled native library in the package's native/ directory
    *
    * @param _callerDir Deprecated parameter, kept for API compatibility
    * @returns Path to the library if found and exists, null otherwise
    */
   static findLibraryPath(_callerDir) {
     const envPath = process.env.TASKER_FFI_LIBRARY_PATH;
-    if (!envPath) {
-      return null;
+    if (envPath) {
+      if (!existsSync(envPath)) {
+        console.warn(`TASKER_FFI_LIBRARY_PATH is set to "${envPath}" but the file does not exist`);
+        return null;
+      }
+      return envPath;
     }
-    if (!existsSync(envPath)) {
-      console.warn(`TASKER_FFI_LIBRARY_PATH is set to "${envPath}" but the file does not exist`);
-      return null;
+    const bundledPath = findBundledNativeLibrary();
+    if (bundledPath && existsSync(bundledPath)) {
+      return bundledPath;
     }
-    return envPath;
+    return null;
   }
   /**
    * Discover the FFI library path.
@@ -1935,6 +1944,21 @@ var FfiLayer = class _FfiLayer {
     }
   }
 };
+var BUNDLED_LIBRARIES = {
+  "linux-x64": "libtasker_ts-linux-x64.so",
+  "linux-arm64": "libtasker_ts-linux-arm64.so",
+  "darwin-arm64": "libtasker_ts-darwin-arm64.dylib"
+};
+function findBundledNativeLibrary() {
+  const key = `${process.platform}-${process.arch}`;
+  const filename2 = BUNDLED_LIBRARIES[key];
+  if (!filename2) {
+    return null;
+  }
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = join(thisDir, "..", "..");
+  return join(packageRoot, "native", filename2);
+}
 
 // src/ffi/index.ts
 init_node_runtime();