@tagma/sdk 0.1.7 → 0.1.9

package/src/pipeline-runner.ts

@@ -1,113 +1,126 @@
-// ═══ PipelineRunner ═══
-//
-// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
-// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
-//
-// Typical sidecar usage:
-//
-//   const runners = new Map<string, PipelineRunner>();
-//
-//   const runner = new PipelineRunner(config, workDir);
-//   runner.subscribe(event => ipcEmit('pipeline_event', event));
-//   runner.start();
-//   runners.set(runner.instanceId, runner);
-//
-//   // Later, from IPC:
-//   runners.get(id)?.abort();
-
-import { runPipeline } from './engine';
-import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
-import type { PipelineConfig, TaskState } from './types';
-import { generateRunId } from './utils';
-
-export type { PipelineEvent, EngineResult };
-
-export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
-
-export class PipelineRunner {
-  /**
-   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
-   * before the engine-assigned runId becomes available.
-   */
-  readonly instanceId: string;
-
-  /**
-   * The runId generated by the engine. Available after the first 'pipeline_start'
-   * event fires (i.e. effectively immediately after start() is called).
-   * null until then.
-   */
-  private _runId: string | null = null;
-  private _status: PipelineRunnerStatus = 'idle';
-  private _result: Promise<EngineResult> | null = null;
-  private _abortController = new AbortController();
-  private _handlers = new Set<(event: PipelineEvent) => void>();
-  private _states: ReadonlyMap<string, TaskState> | null = null;
-
-  constructor(
-    private readonly config: PipelineConfig,
-    private readonly workDir: string,
-    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
-  ) {
-    this.instanceId = generateRunId();
-  }
-
-  get runId(): string | null { return this._runId; }
-  get status(): PipelineRunnerStatus { return this._status; }
-
-  /**
-   * Start the pipeline. Calling start() more than once returns the same Promise.
-   */
-  start(): Promise<EngineResult> {
-    if (this._result) return this._result;
-
-    this._status = 'running';
-    this._result = runPipeline(this.config, this.workDir, {
-      ...this.opts,
-      signal: this._abortController.signal,
-      onEvent: (event) => {
-        if (event.type === 'pipeline_start') {
-          this._runId = event.runId;
-        }
-        if (event.type === 'pipeline_end') {
-          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
-        }
-        for (const h of this._handlers) h(event);
-      },
-    }).then(result => {
-      this._states = result.states;
-      if (this._status === 'running') this._status = 'done';
-      return result;
-    }).catch(err => {
-      this._status = 'aborted';
-      throw err;
-    });
-
-    return this._result;
-  }
-
-  /**
-   * Cancel the running pipeline. Safe to call multiple times or before start().
-   */
-  abort(reason?: string): void {
-    this._status = 'aborted';
-    this._abortController.abort(reason);
-  }
-
-  /**
-   * Snapshot of task states. Populated after the run completes.
-   * During a run, listen to subscribe() events for incremental updates.
-   */
-  getStates(): ReadonlyMap<string, TaskState> | null {
-    return this._states;
-  }
-
-  /**
-   * Subscribe to pipeline/task events. Returns an unsubscribe function.
-   * Events are emitted synchronously in the engine's event loop, so keep
-   * handlers non-blocking (e.g. queue to IPC, do not await inside).
-   */
-  subscribe(handler: (event: PipelineEvent) => void): () => void {
-    this._handlers.add(handler);
-    return () => this._handlers.delete(handler);
-  }
-}
+// ═══ PipelineRunner ═══
+//
+// Wraps runPipeline in a lifecycle object suited for multi-pipeline management
+// in sidecar / Tauri IPC scenarios. Each instance controls one pipeline run.
+//
+// Typical sidecar usage:
+//
+//   const runners = new Map<string, PipelineRunner>();
+//
+//   const runner = new PipelineRunner(config, workDir);
+//   runner.subscribe(event => ipcEmit('pipeline_event', event));
+//   runner.start();
+//   runners.set(runner.instanceId, runner);
+//
+//   // Later, from IPC:
+//   runners.get(id)?.abort();
+
+import { runPipeline } from './engine';
+import type { EngineResult, PipelineEvent, RunPipelineOptions } from './engine';
+import type { PipelineConfig, TaskState } from './types';
+import { generateRunId } from './utils';
+
+export type { PipelineEvent, EngineResult };
+
+export type PipelineRunnerStatus = 'idle' | 'running' | 'done' | 'aborted';
+
+export class PipelineRunner {
+  /**
+   * Stable ID assigned before start() — safe to use as a Map key in the sidecar
+   * before the engine-assigned runId becomes available.
+   */
+  readonly instanceId: string;
+
+  /**
+   * The runId generated by the engine. Available after the first 'pipeline_start'
+   * event fires (i.e. effectively immediately after start() is called).
+   * null until then.
+   */
+  private _runId: string | null = null;
+  private _status: PipelineRunnerStatus = 'idle';
+  private _result: Promise<EngineResult> | null = null;
+  private _abortController = new AbortController();
+  private _handlers = new Set<(event: PipelineEvent) => void>();
+  private _states: ReadonlyMap<string, TaskState> | null = null;
+  private _statesMirror = new Map<string, TaskState>();
+
+  constructor(
+    private readonly config: PipelineConfig,
+    private readonly workDir: string,
+    private readonly opts: Omit<RunPipelineOptions, 'signal' | 'onEvent'> = {},
+  ) {
+    this.instanceId = generateRunId();
+  }
+
+  get runId(): string | null { return this._runId; }
+  get status(): PipelineRunnerStatus { return this._status; }
+
+  /**
+   * Start the pipeline. Calling start() more than once returns the same Promise.
+   */
+  start(): Promise<EngineResult> {
+    if (this._result) return this._result;
+
+    this._status = 'running';
+    this._result = runPipeline(this.config, this.workDir, {
+      ...this.opts,
+      signal: this._abortController.signal,
+      onEvent: (event) => {
+        if (event.type === 'pipeline_start') {
+          this._runId = event.runId;
+          // Initialize the live mirror with the full initial state snapshot
+          for (const [id, state] of event.states) {
+            this._statesMirror.set(id, { ...state });
+          }
+        }
+        if (event.type === 'task_status_change') {
+          // Keep the mirror up to date so getStates() works during the run
+          this._statesMirror.set(event.taskId, event.state);
+        }
+        if (event.type === 'pipeline_end') {
+          this._status = this._abortController.signal.aborted ? 'aborted' : 'done';
+        }
+        for (const h of this._handlers) h(event);
+      },
+    }).then(result => {
+      this._states = result.states;
+      if (this._status === 'running') this._status = 'done';
+      return result;
+    }).catch(err => {
+      this._status = 'aborted';
+      throw err;
+    });
+
+    return this._result;
+  }
+
+  /**
+   * Cancel the running pipeline. Safe to call multiple times or before start().
+   */
+  abort(reason?: string): void {
+    this._status = 'aborted';
+    this._abortController.abort(reason);
+  }
+
+  /**
+   * Live snapshot of task states. Available from the first pipeline_start event onward
+   * (i.e. as soon as start() is called) and remains accessible after the run completes.
+   * Returns null only if the pipeline has never started.
+   */
+  getStates(): ReadonlyMap<string, TaskState> | null {
+    if (this._states) return this._states;
+    // Return a snapshot copy so callers cannot mutate SDK-internal state.
+    if (this._statesMirror.size > 0) return new Map([...this._statesMirror]);
+    return null;
+  }
+
+  /**
+   * Subscribe to pipeline/task events. Returns an unsubscribe function.
+   * Events are emitted synchronously in the engine's event loop, so keep
+   * handlers non-blocking (e.g. queue to IPC, do not await inside).
+   */
+  subscribe(handler: (event: PipelineEvent) => void): () => void {
+    this._handlers.add(handler);
+    return () => this._handlers.delete(handler);
+  }
+}