@tagma/sdk 0.1.7 → 0.1.9

package/README.md

@@ -113,7 +113,10 @@ Executes the pipeline. Returns `{ success, runId, logPath, summary, states }`.
 Options:
 - `approvalGateway` -- custom `ApprovalGateway` instance (defaults to `InMemoryApprovalGateway`)
 - `signal` -- `AbortSignal` to cancel the run externally
-- `onEvent` -- callback for real-time `PipelineEvent` updates (task status changes, pipeline start/end)
+- `onEvent` -- callback for real-time `PipelineEvent` updates:
+  - `pipeline_start` — pipeline began; includes `states: ReadonlyMap<taskId, TaskState>` (initial snapshot of all tasks at `waiting`)
+  - `task_status_change` — a task changed status; includes `state: TaskState` (complete snapshot at the time of change: `startedAt` is populated before the `running` event; `result` and `finishedAt` are populated before any terminal-status event)
+  - `pipeline_end` — pipeline finished; includes `success: boolean`
 - `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/logs/` (default: 20)
 
 ### `PipelineRunner`
@@ -133,8 +136,9 @@ runner.start(); // returns Promise<EngineResult>, idempotent
 // Cancel from IPC
 runner.abort();
 
-// After completion
-const states = runner.getStates(); // ReadonlyMap<taskId, TaskState>
+// Available from the first pipeline_start event onward (not just after completion)
+// Returns null only if the pipeline has never started
+const states = runner.getStates(); // ReadonlyMap<taskId, TaskState> | null
 ```
 
 Properties:
@@ -184,7 +188,7 @@ const yaml = serializePipeline(config);
 | `moveTrack(config, trackId, toIndex)` | Reorder a track |
 | `updateTrack(config, trackId, fields)` | Patch track fields (not tasks) |
 | `upsertTask(config, trackId, task)` | Insert or replace a task |
-| `removeTask(config, trackId, taskId)` | Remove a task |
+| `removeTask(config, trackId, taskId, cleanRefs?)` | Remove a task; pass `cleanRefs: true` to also strip dangling `depends_on` / `continue_from` references. Only refs that resolve to the deleted task are removed — same-named tasks in other tracks are unaffected |
 | `moveTask(config, trackId, taskId, toIndex)` | Reorder a task within its track |
 | `transferTask(config, fromTrackId, taskId, toTrackId)` | Move a task across tracks |
 
@@ -220,7 +224,7 @@ Use `validateRaw` for editing raw configs in a UI; use `validateConfig` after `r
 
 Validates a raw pipeline config without resolving inheritance or executing anything. Returns a flat list of `{ path, message }` objects — empty array means valid.
 
-Checks: required fields, `prompt`/`command` exclusivity, `depends_on`/`continue_from` reference integrity, circular dependency detection.
+Checks: required fields, `prompt`/`command` exclusivity, `depends_on`/`continue_from` reference integrity (including ambiguous bare refs that exist in multiple tracks — use `trackId.taskId` to disambiguate), circular dependency detection.
 
 Does **not** check plugin registration (plugins may not be loaded at edit time).
 
@@ -231,6 +235,20 @@ if (errors.length > 0) {
 }
 ```
 
+### `buildRawDag(config: RawPipelineConfig): RawDag`
+
+Extracts the topology of a raw (unresolved) pipeline config as a graph — no `workDir` or plugin registration required. Intended for the visual editor to render the flow graph during editing.
+
+Returns `{ nodes: ReadonlyMap<taskId, RawDagNode>, edges: { from, to }[] }` where each edge represents a dependency (from must complete before to). Template-expansion tasks (`use:` field) and unresolvable refs are silently skipped.
+
+```ts
+const { nodes, edges } = buildRawDag(draftConfig);
+// nodes — keyed by "trackId.taskId"
+// edges — [{ from: "track.taskA", to: "track.taskB" }, ...]
+```
+
+Use `buildDag` instead when you have a fully resolved `PipelineConfig` and need topological sort order.
+
 ## Related Packages
 
 | Package | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "workspaces": [
     "plugins/*"

package/src/adapters/stdin-approval.ts

@@ -1,117 +1,117 @@
-import * as readline from 'readline';
-import type { ApprovalGateway, ApprovalRequest } from '../approval';
-
-// ═══ CLI Stdin Adapter ═══
-//
-// Subscribes to the gateway's 'requested' events, prompts the user on stdout,
-// reads a line from stdin, and calls gateway.resolve(). Handles at most one
-// prompt at a time — additional requests queue up.
-
-export interface StdinApprovalAdapter {
-  readonly detach: () => void;
-}
-
-export function attachStdinApprovalAdapter(gateway: ApprovalGateway): StdinApprovalAdapter {
-  const queue: ApprovalRequest[] = [];
-  let processing = false;
-  let rl: readline.Interface | null = null;
-
-  function ensureReadline(): readline.Interface {
-    if (!rl) {
-      rl = readline.createInterface({ input: process.stdin, terminal: false });
-    }
-    return rl;
-  }
-
-  function readOneLine(): Promise<string> {
-    return new Promise((resolvePromise) => {
-      const reader = ensureReadline();
-      const handler = (line: string): void => {
-        reader.off('line', handler);
-        resolvePromise(line);
-      };
-      reader.on('line', handler);
-    });
-  }
-
-  async function processNext(): Promise<void> {
-    if (processing) return;
-    processing = true;
-    try {
-      while (queue.length > 0) {
-        const req = queue.shift()!;
-        // If the request was already resolved by another path while queued, skip it.
-        if (!gateway.pending().some((p) => p.id === req.id)) continue;
-
-        const optionsStr = req.options.join(' / ');
-        process.stdout.write(
-          `\n[APPROVAL REQUIRED] ${req.message}\n` +
-            `  id:      ${req.id}\n` +
-            `  task:    ${req.taskId}${req.trackId ? ` (track: ${req.trackId})` : ''}\n` +
-            `  options: ${optionsStr}\n` +
-            `  > `,
-        );
-
-        const input = (await readOneLine()).trim().toLowerCase();
-
-        const approveAliases = new Set(['approve', 'yes', 'y', 'ok', 'true', '1']);
-        const rejectAliases = new Set(['reject', 'no', 'n', 'deny', 'false', '0']);
-        const matchedOption = req.options.find((o) => o.toLowerCase() === input);
-
-        if (matchedOption) {
-          const isReject = rejectAliases.has(matchedOption.toLowerCase());
-          gateway.resolve(req.id, {
-            outcome: isReject ? 'rejected' : 'approved',
-            choice: matchedOption,
-            actor: 'cli',
-          });
-        } else if (approveAliases.has(input)) {
-          gateway.resolve(req.id, { outcome: 'approved', choice: input, actor: 'cli' });
-        } else if (rejectAliases.has(input)) {
-          gateway.resolve(req.id, {
-            outcome: 'rejected',
-            choice: input,
-            actor: 'cli',
-            reason: 'user rejected via CLI',
-          });
-        } else {
-          process.stdout.write(`  unrecognized input "${input}" — treating as rejection\n`);
-          gateway.resolve(req.id, {
-            outcome: 'rejected',
-            actor: 'cli',
-            reason: `unrecognized CLI input: ${input}`,
-          });
-        }
-      }
-    } finally {
-      processing = false;
-    }
-  }
-
-  const unsubscribe = gateway.subscribe((event) => {
-    switch (event.type) {
-      case 'requested':
-        queue.push(event.request);
-        void processNext();
-        return;
-      case 'resolved':
-      case 'expired':
-      case 'aborted': {
-        // Drop from queue if it's still waiting its turn.
-        const idx = queue.findIndex((r) => r.id === event.request.id);
-        if (idx >= 0) queue.splice(idx, 1);
-        return;
-      }
-    }
-  });
-
-  return {
-    detach: () => {
-      unsubscribe();
-      if (rl) {
-        rl.close();
-        rl = null;
-      }
-    },
-  };
-}
+import * as readline from 'readline';
+import type { ApprovalGateway, ApprovalRequest } from '../approval';
+
+// ═══ CLI Stdin Adapter ═══
+//
+// Subscribes to the gateway's 'requested' events, prompts the user on stdout,
+// reads a line from stdin, and calls gateway.resolve(). Handles at most one
+// prompt at a time — additional requests queue up.
+
+export interface StdinApprovalAdapter {
+  readonly detach: () => void;
+}
+
+export function attachStdinApprovalAdapter(gateway: ApprovalGateway): StdinApprovalAdapter {
+  const queue: ApprovalRequest[] = [];
+  let processing = false;
+  let rl: readline.Interface | null = null;
+
+  function ensureReadline(): readline.Interface {
+    if (!rl) {
+      rl = readline.createInterface({ input: process.stdin, terminal: false });
+    }
+    return rl;
+  }
+
+  function readOneLine(): Promise<string> {
+    return new Promise((resolvePromise) => {
+      const reader = ensureReadline();
+      const handler = (line: string): void => {
+        reader.off('line', handler);
+        resolvePromise(line);
+      };
+      reader.on('line', handler);
+    });
+  }
+
+  async function processNext(): Promise<void> {
+    if (processing) return;
+    processing = true;
+    try {
+      while (queue.length > 0) {
+        const req = queue.shift()!;
+        // If the request was already resolved by another path while queued, skip it.
+        if (!gateway.pending().some((p) => p.id === req.id)) continue;
+
+        const optionsStr = req.options.join(' / ');
+        process.stdout.write(
+          `\n[APPROVAL REQUIRED] ${req.message}\n` +
+            `  id:      ${req.id}\n` +
+            `  task:    ${req.taskId}${req.trackId ? ` (track: ${req.trackId})` : ''}\n` +
+            `  options: ${optionsStr}\n` +
+            `  > `,
+        );
+
+        const input = (await readOneLine()).trim().toLowerCase();
+
+        const approveAliases = new Set(['approve', 'yes', 'y', 'ok', 'true', '1']);
+        const rejectAliases = new Set(['reject', 'no', 'n', 'deny', 'false', '0']);
+        const matchedOption = req.options.find((o) => o.toLowerCase() === input);
+
+        if (matchedOption) {
+          const isReject = rejectAliases.has(matchedOption.toLowerCase());
+          gateway.resolve(req.id, {
+            outcome: isReject ? 'rejected' : 'approved',
+            choice: matchedOption,
+            actor: 'cli',
+          });
+        } else if (approveAliases.has(input)) {
+          gateway.resolve(req.id, { outcome: 'approved', choice: input, actor: 'cli' });
+        } else if (rejectAliases.has(input)) {
+          gateway.resolve(req.id, {
+            outcome: 'rejected',
+            choice: input,
+            actor: 'cli',
+            reason: 'user rejected via CLI',
+          });
+        } else {
+          process.stdout.write(`  unrecognized input "${input}" — treating as rejection\n`);
+          gateway.resolve(req.id, {
+            outcome: 'rejected',
+            actor: 'cli',
+            reason: `unrecognized CLI input: ${input}`,
+          });
+        }
+      }
+    } finally {
+      processing = false;
+    }
+  }
+
+  const unsubscribe = gateway.subscribe((event) => {
+    switch (event.type) {
+      case 'requested':
+        queue.push(event.request);
+        void processNext();
+        return;
+      case 'resolved':
+      case 'expired':
+      case 'aborted': {
+        // Drop from queue if it's still waiting its turn.
+        const idx = queue.findIndex((r) => r.id === event.request.id);
+        if (idx >= 0) queue.splice(idx, 1);
+        return;
+      }
+    }
+  });
+
+  return {
+    detach: () => {
+      unsubscribe();
+      if (rl) {
+        rl.close();
+        rl = null;
+      }
+    },
+  };
+}

package/src/adapters/websocket-approval.ts

@@ -1,144 +1,175 @@
-import type { ApprovalGateway, ApprovalEvent } from '../approval';
-
-// ═══ WebSocket Approval Adapter ═══
-//
-// Bridges the ApprovalGateway to WebSocket clients (e.g. a frontend UI).
-// Mirrors the stdin-approval adapter pattern: subscribe to gateway events,
-// forward them as JSON to all connected clients, and call gateway.resolve()
-// when a client sends a resolution message.
-//
-// Protocol — server → client:
-//   { type: 'pending',             requests: ApprovalRequest[] }   ← sent on connect
-//   { type: 'approval_requested',  request:  ApprovalRequest }
-//   { type: 'approval_resolved',   request:  ApprovalRequest, decision: ApprovalDecision }
-//   { type: 'approval_expired',    request:  ApprovalRequest }
-//   { type: 'approval_aborted',    request:  ApprovalRequest, reason: string }
-//
-// Protocol — client → server:
-//   { type: 'resolve', approvalId: string, outcome: 'approved'|'rejected',
-//     choice?: string, actor?: string, reason?: string }
-
-export interface WebSocketApprovalAdapterOptions {
-  port?: number;      // default: 3000
-  hostname?: string;  // default: 'localhost'
-}
-
-export interface WebSocketApprovalAdapter {
-  readonly port: number;
-  readonly detach: () => void;
-}
-
-export function attachWebSocketApprovalAdapter(
-  gateway: ApprovalGateway,
-  options: WebSocketApprovalAdapterOptions = {},
-): WebSocketApprovalAdapter {
-  const port = options.port ?? 3000;
-  const hostname = options.hostname ?? 'localhost';
-
-  const clients = new Set<import('bun').ServerWebSocket<unknown>>();
-
-  function broadcast(msg: unknown): void {
-    const text = JSON.stringify(msg);
-    for (const ws of clients) {
-      ws.send(text);
-    }
-  }
-
-  const unsubscribe = gateway.subscribe((event: ApprovalEvent) => {
-    switch (event.type) {
-      case 'requested':
-        broadcast({ type: 'approval_requested', request: event.request });
-        break;
-      case 'resolved':
-        broadcast({ type: 'approval_resolved', request: event.request, decision: event.decision });
-        break;
-      case 'expired':
-        broadcast({ type: 'approval_expired', request: event.request });
-        break;
-      case 'aborted':
-        broadcast({ type: 'approval_aborted', request: event.request, reason: event.reason });
-        break;
-    }
-  });
-
-  const server = Bun.serve({
-    port,
-    hostname,
-
-    fetch(req, server) {
-      if (server.upgrade(req)) return undefined;
-      return new Response('tagma-sdk WebSocket approval endpoint', { status: 426 });
-    },
-
-    websocket: {
-      open(ws) {
-        clients.add(ws);
-        // Sync current pending approvals to newly connected client.
-        ws.send(JSON.stringify({ type: 'pending', requests: gateway.pending() }));
-      },
-
-      message(ws, raw) {
-        let msg: unknown;
-        try {
-          msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
-        } catch {
-          ws.send(JSON.stringify({ type: 'error', message: 'invalid JSON' }));
-          return;
-        }
-
-        if (!isResolveMessage(msg)) {
-          ws.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
-          return;
-        }
-
-        const ok = gateway.resolve(msg.approvalId, {
-          outcome: msg.outcome,
-          choice: msg.choice,
-          actor: msg.actor ?? 'websocket',
-          reason: msg.reason,
-        });
-
-        if (!ok) {
-          ws.send(JSON.stringify({
-            type: 'error',
-            message: `approval ${msg.approvalId} not found or already resolved`,
-          }));
-        }
-      },
-
-      close(ws) {
-        clients.delete(ws);
-      },
-    },
-  });
-
-  return {
-    port: server.port!,
-    detach() {
-      unsubscribe();
-      clients.clear();
-      server.stop(true);
-    },
-  };
-}
-
-// ── Type guard ──
-
-interface ResolveMessage {
-  type: 'resolve';
-  approvalId: string;
-  outcome: 'approved' | 'rejected';
-  choice?: string;
-  actor?: string;
-  reason?: string;
-}
-
-function isResolveMessage(v: unknown): v is ResolveMessage {
-  if (typeof v !== 'object' || v === null) return false;
-  const m = v as Record<string, unknown>;
-  return (
-    m['type'] === 'resolve' &&
-    typeof m['approvalId'] === 'string' &&
-    (m['outcome'] === 'approved' || m['outcome'] === 'rejected')
-  );
-}
+import type { ApprovalGateway, ApprovalEvent } from '../approval';
+
+// ═══ WebSocket Approval Adapter ═══
+//
+// Bridges the ApprovalGateway to WebSocket clients (e.g. a frontend UI).
+// Mirrors the stdin-approval adapter pattern: subscribe to gateway events,
+// forward them as JSON to all connected clients, and call gateway.resolve()
+// when a client sends a resolution message.
+//
+// Protocol — server → client:
+//   { type: 'pending',             requests: ApprovalRequest[] }   ← sent on connect
+//   { type: 'approval_requested',  request:  ApprovalRequest }
+//   { type: 'approval_resolved',   request:  ApprovalRequest, decision: ApprovalDecision }
+//   { type: 'approval_expired',    request:  ApprovalRequest }
+//   { type: 'approval_aborted',    request:  ApprovalRequest, reason: string }
+//
+// Protocol — client → server:
+//   { type: 'resolve', approvalId: string, outcome: 'approved'|'rejected',
+//     choice?: string, actor?: string, reason?: string }
+
+export interface WebSocketApprovalAdapterOptions {
+  port?: number;      // default: 3000
+  hostname?: string;  // default: 'localhost'
+}
+
+export interface WebSocketApprovalAdapter {
+  readonly port: number;
+  readonly detach: () => void;
+}
+
+// Maximum allowed message payload (bytes) to prevent DoS via oversized messages.
+const MAX_PAYLOAD_BYTES = 4_096;
+// Per-client rate limit: at most this many messages per window.
+const RATE_LIMIT_MAX = 10;
+const RATE_LIMIT_WINDOW_MS = 1_000;
+
+export function attachWebSocketApprovalAdapter(
+  gateway: ApprovalGateway,
+  options: WebSocketApprovalAdapterOptions = {},
+): WebSocketApprovalAdapter {
+  const port = options.port ?? 3000;
+  const hostname = options.hostname ?? 'localhost';
+
+  type WS = import('bun').ServerWebSocket<unknown>;
+  const clients = new Set<WS>();
+  const clientRates = new Map<WS, { count: number; resetAt: number }>();
+
+  function broadcast(msg: unknown): void {
+    const text = JSON.stringify(msg);
+    for (const ws of clients) {
+      ws.send(text);
+    }
+  }
+
+  const unsubscribe = gateway.subscribe((event: ApprovalEvent) => {
+    switch (event.type) {
+      case 'requested':
+        broadcast({ type: 'approval_requested', request: event.request });
+        break;
+      case 'resolved':
+        broadcast({ type: 'approval_resolved', request: event.request, decision: event.decision });
+        break;
+      case 'expired':
+        broadcast({ type: 'approval_expired', request: event.request });
+        break;
+      case 'aborted':
+        broadcast({ type: 'approval_aborted', request: event.request, reason: event.reason });
+        break;
+    }
+  });
+
+  const server = Bun.serve({
+    port,
+    hostname,
+
+    fetch(req, server) {
+      if (server.upgrade(req)) return undefined;
+      return new Response('tagma-sdk WebSocket approval endpoint', { status: 426 });
+    },
+
+    websocket: {
+      open(ws) {
+        clients.add(ws);
+        // Sync current pending approvals to newly connected client.
+        ws.send(JSON.stringify({ type: 'pending', requests: gateway.pending() }));
+      },
+
+      message(ws, raw) {
+        const rawStr = typeof raw === 'string' ? raw : raw.toString();
+
+        // Payload size guard — reject oversized messages before parsing.
+        if (rawStr.length > MAX_PAYLOAD_BYTES) {
+          ws.send(JSON.stringify({ type: 'error', message: 'message too large' }));
+          return;
+        }
+
+        // Per-client rate limit.
+        const now = Date.now();
+        const rate = clientRates.get(ws) ?? { count: 0, resetAt: now + RATE_LIMIT_WINDOW_MS };
+        if (now >= rate.resetAt) {
+          rate.count = 0;
+          rate.resetAt = now + RATE_LIMIT_WINDOW_MS;
+        }
+        rate.count++;
+        clientRates.set(ws, rate);
+        if (rate.count > RATE_LIMIT_MAX) {
+          ws.send(JSON.stringify({ type: 'error', message: 'rate limit exceeded' }));
+          return;
+        }
+
+        let msg: unknown;
+        try {
+          msg = JSON.parse(rawStr);
+        } catch {
+          ws.send(JSON.stringify({ type: 'error', message: 'invalid JSON' }));
+          return;
+        }
+
+        if (!isResolveMessage(msg)) {
+          ws.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
+          return;
+        }
+
+        const ok = gateway.resolve(msg.approvalId, {
+          outcome: msg.outcome,
+          choice: msg.choice,
+          actor: msg.actor ?? 'websocket',
+          reason: msg.reason,
+        });
+
+        if (!ok) {
+          ws.send(JSON.stringify({
+            type: 'error',
+            message: `approval ${msg.approvalId} not found or already resolved`,
+          }));
+        }
+      },
+
+      close(ws) {
+        clients.delete(ws);
+        clientRates.delete(ws);
+      },
+    },
+  });
+
+  return {
+    port: server.port!,
+    detach() {
+      unsubscribe();
+      clients.clear();
+      server.stop(true);
+    },
+  };
+}
+
+// ── Type guard ──
+
+interface ResolveMessage {
+  type: 'resolve';
+  approvalId: string;
+  outcome: 'approved' | 'rejected';
+  choice?: string;
+  actor?: string;
+  reason?: string;
+}
+
+function isResolveMessage(v: unknown): v is ResolveMessage {
+  if (typeof v !== 'object' || v === null) return false;
+  const m = v as Record<string, unknown>;
+  return (
+    m['type'] === 'resolve' &&
+    typeof m['approvalId'] === 'string' &&
+    (m['outcome'] === 'approved' || m['outcome'] === 'rejected')
+  );
+}

package/src/approval.ts

@@ -16,6 +16,9 @@ export type {
   ApprovalListener, ApprovalGateway,
 } from '@tagma/types';
 
+// Default options presented to the approver when the caller does not specify any.
+const DEFAULT_APPROVAL_OPTIONS = ['approve', 'reject'] as const;
+
 // ═══ Default In-Memory Implementation ═══
 
 interface PendingEntry {
@@ -37,7 +40,7 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
       taskId: req.taskId,
       trackId: req.trackId,
       message: req.message,
-      options: req.options && req.options.length > 0 ? req.options : ['approve', 'reject'],
+      options: req.options && req.options.length > 0 ? req.options : DEFAULT_APPROVAL_OPTIONS,
       timeoutMs: req.timeoutMs,
       metadata: req.metadata,
     };