@tagma/sdk 0.4.14 → 0.4.16

package/src/task-ref.ts

@@ -0,0 +1,120 @@
+// ═══ Task reference resolution — single source of truth ═══
+//
+// Before this module existed, four sites each carried their own copy of the
+// "what is a valid id" + "how do I resolve a bare / same-track-shorthand /
+// fully qualified ref" logic:
+//
+//   - dag.ts/buildDag         (threw on unresolved, threw on ambiguous)
+//   - dag.ts/buildRawDag      (silently skipped unresolved and ambiguous)
+//   - validate-raw.ts         (reported both as errors, with different wording)
+//   - engine.ts/resolveRefInDag  (returned null on ambiguous)
+//
+// In addition, the editor shipped its own regex for id validation in
+// `shared/config-id.ts` and a test-local copy in `config-id-generation.test.ts`,
+// creating multiple places where the character set could drift from the
+// validator. Bugs observed downstream (silent context loss when two tracks
+// happened to share a bare task name; editor-generated ids occasionally
+// failing SDK validate-raw) all traced back to this duplication.
+//
+// Callers now build a TaskIndex once and use `resolveTaskRef` to classify
+// each reference, then decide themselves whether to throw / warn / skip —
+// instead of re-implementing the index build and the lookup logic.
+
+import type { PipelineConfig, RawPipelineConfig } from './types';
+
+/**
+ * D8: task and track ids must match this pattern. No dots: the `.` is the
+ * qualified-id separator ("trackId.taskId"), so allowing it inside either
+ * part would make qid parsing ambiguous and break every resolver below.
+ */
+export const TASK_ID_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+export function isValidTaskId(id: unknown): id is string {
+  return typeof id === 'string' && TASK_ID_RE.test(id);
+}
+
+/** Canonical qualified form used throughout the engine. */
+export function qualifyTaskId(trackId: string, taskId: string): string {
+  return `${trackId}.${taskId}`;
+}
+
+/** Does the reference already include a track prefix? */
+export function isQualifiedRef(ref: string): boolean {
+  return ref.includes('.');
+}
+
+/**
+ * Sentinel stored in `TaskIndex.bareToQualified` when a bare task id is
+ * shared by more than one track, making it unresolvable without a prefix.
+ * Exposed so callers that want to inspect the index directly know what to
+ * look for — but prefer `resolveTaskRef` which returns a typed `kind`.
+ */
+export const AMBIGUOUS = '__ambiguous__';
+
+export interface TaskIndex {
+  /** All fully-qualified ids ("trackId.taskId") present in the config. */
+  readonly allQualified: ReadonlySet<string>;
+  /** bare taskId → qid, or the {@link AMBIGUOUS} sentinel. */
+  readonly bareToQualified: ReadonlyMap<string, string>;
+}
+
+/**
+ * Build the index used by {@link resolveTaskRef}. Tolerant of partially
+ * malformed configs: tracks or tasks missing an `id` are skipped so the
+ * editor can call this during real-time validation on in-progress edits.
+ */
+export function buildTaskIndex(config: RawPipelineConfig | PipelineConfig): TaskIndex {
+  const allQualified = new Set<string>();
+  const bareToQualified = new Map<string, string>();
+  for (const track of config.tracks ?? []) {
+    if (!track?.id) continue;
+    for (const task of track.tasks ?? []) {
+      if (!task?.id) continue;
+      const qid = qualifyTaskId(track.id, task.id);
+      allQualified.add(qid);
+      if (bareToQualified.has(task.id)) {
+        bareToQualified.set(task.id, AMBIGUOUS);
+      } else {
+        bareToQualified.set(task.id, qid);
+      }
+    }
+  }
+  return { allQualified, bareToQualified };
+}
+
+export type RefResolution =
+  | { readonly kind: 'resolved'; readonly qid: string }
+  | { readonly kind: 'ambiguous'; readonly ref: string }
+  | { readonly kind: 'not_found'; readonly ref: string };
+
+/**
+ * Resolve a dependency / continue_from reference to a canonical qid.
+ *
+ *  1. If the ref already contains a `.`, treat it as fully qualified —
+ *     return `resolved` when the qid exists, `not_found` otherwise.
+ *  2. Otherwise, prefer the same-track shorthand (`fromTrackId.ref`).
+ *  3. Fall back to a global bare lookup. Returns `ambiguous` when more
+ *     than one track has a task with that bare name.
+ *
+ * Callers decide the policy: `buildDag` throws on non-resolved, `buildRawDag`
+ * skips silently, `validateRaw` emits a structured ValidationError.
+ */
+export function resolveTaskRef(
+  ref: string,
+  fromTrackId: string,
+  index: TaskIndex,
+): RefResolution {
+  if (isQualifiedRef(ref)) {
+    return index.allQualified.has(ref)
+      ? { kind: 'resolved', qid: ref }
+      : { kind: 'not_found', ref };
+  }
+  const sameTrack = qualifyTaskId(fromTrackId, ref);
+  if (index.allQualified.has(sameTrack)) {
+    return { kind: 'resolved', qid: sameTrack };
+  }
+  const global = index.bareToQualified.get(ref);
+  if (global === AMBIGUOUS) return { kind: 'ambiguous', ref };
+  if (global !== undefined) return { kind: 'resolved', qid: global };
+  return { kind: 'not_found', ref };
+}

package/src/triggers/file.ts

@@ -1,164 +1,164 @@
-import { watch } from 'chokidar';
-import { resolve, dirname } from 'path';
-import { mkdir } from 'fs/promises';
-import type { TriggerPlugin, TriggerContext } from '../types';
-import { parseDuration, validatePath } from '../utils';
-import { TriggerTimeoutError } from '../engine';
-
-const IS_WINDOWS = process.platform === 'win32';
-
-function pathsEqual(a: string, b: string): boolean {
-  return IS_WINDOWS ? a.toLowerCase() === b.toLowerCase() : a === b;
-}
-
-export const FileTrigger: TriggerPlugin = {
-  name: 'file',
-  schema: {
-    description: 'Wait for a file to appear or be modified before the task runs.',
-    fields: {
-      path: {
-        type: 'path',
-        required: true,
-        description: 'Path to the file to watch (relative to workDir or absolute).',
-        placeholder: 'e.g. build/output.json',
-      },
-      timeout: {
-        type: 'duration',
-        description: 'Maximum wait time (e.g. 30s, 5m). Omit or 0 to wait indefinitely.',
-        placeholder: '30s',
-      },
-    },
-  },
-
-  watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
-    const filePath = config.path as string;
-    if (!filePath) throw new Error(`file trigger: "path" is required`);
-
-    const safePath = validatePath(filePath, ctx.workDir);
-    const timeoutMs = config.timeout != null ? parseDuration(String(config.timeout)) : 0;
-
-    // Hoist the async work into a named async function so the Promise
-    // constructor itself is synchronous — avoids the no-async-promise-executor
-    // lint error and ensures exceptions are always propagated via reject().
-    async function start(
-      resolve_p: (value: unknown) => void,
-      reject: (reason?: unknown) => void,
-    ): Promise<void> {
-      if (ctx.signal.aborted) {
-        reject(new Error('Pipeline aborted'));
-        return;
-      }
-
-      let settled = false;
-      let timer: ReturnType<typeof setTimeout> | null = null;
-
-      // Ensure the parent directory exists so the watcher doesn't fail
-      // with ENOENT for nested paths like `build/output/result.json`.
-      const dir = dirname(safePath);
-      try {
-        await mkdir(dir, { recursive: true });
-      } catch {
-        /* best effort — dir may already exist */
-      }
-
-      // Pass `cwd: dir` so chokidar resolves paths relative to the watched
-      // directory. The 'add'/'change' events will then carry paths relative
-      // to `dir`, which we resolve with `resolve(dir, addedPath)` for an
-      // accurate absolute comparison — fixing the ambiguous process.cwd()
-      // resolution of the previous implementation.
-      const watcher = watch(dir, {
-        ignoreInitial: true,
-        depth: 0,
-        cwd: dir,
-        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
-      });
-
-      const cleanup = () => {
-        if (settled) return;
-        settled = true;
-        watcher.close().catch(() => {
-          /* ignore */
-        });
-        if (timer) clearTimeout(timer);
-        ctx.signal.removeEventListener('abort', onAbort);
-      };
-
-      const onAbort = () => {
-        cleanup();
-        reject(new Error('Pipeline aborted'));
-      };
-
-      watcher.on('add', (addedPath: string) => {
-        if (settled) return;
-        if (pathsEqual(resolve(dir, addedPath), safePath)) {
-          cleanup();
-          resolve_p({ path: safePath });
-        }
-      });
-
-      // Also fire on 'change' so that overwriting an existing file is detected.
-      // Without this, upstream tasks that truncate-and-rewrite a file emit only
-      // a 'change' event and the downstream trigger would never resolve.
-      watcher.on('change', (changedPath: string) => {
-        if (settled) return;
-        if (pathsEqual(resolve(dir, changedPath), safePath)) {
-          cleanup();
-          resolve_p({ path: safePath });
-        }
-      });
-
-      watcher.on('error', (err: unknown) => {
-        if (settled) return;
-        cleanup();
-        reject(
-          new Error(
-            `file trigger watch error: ${err instanceof Error ? err.message : String(err)}`,
-          ),
-        );
-      });
-
-      // After the watcher finishes its initial scan, check if the file already exists.
-      // Doing this inside 'ready' eliminates the race window between existence check
-      // and watcher startup, so we neither miss events nor double-resolve.
-      watcher.on('ready', () => {
-        if (settled) return;
-        Bun.file(safePath)
-          .exists()
-          .then((exists) => {
-            if (settled) return;
-            if (exists) {
-              cleanup();
-              resolve_p({ path: safePath });
-            }
-          })
-          .catch((err: unknown) => {
-            if (settled) return;
-            cleanup();
-            reject(
-              new Error(
-                `file trigger existence check failed: ${err instanceof Error ? err.message : String(err)}`,
-              ),
-            );
-          });
-      });
-
-      if (timeoutMs > 0) {
-        timer = setTimeout(() => {
-          if (settled) return;
-          cleanup();
-          reject(
-            new TriggerTimeoutError(
-              `file trigger timeout: ${filePath} did not appear within ${config.timeout}`,
-            ),
-          );
-        }, timeoutMs);
-      }
-
-      ctx.signal.addEventListener('abort', onAbort);
-    }
-
-    return new Promise((resolve_p, reject) => {
-      start(resolve_p, reject).catch(reject);
-    });
-  },
-};
+import { watch } from 'chokidar';
+import { resolve, dirname } from 'path';
+import { mkdir } from 'fs/promises';
+import type { TriggerPlugin, TriggerContext } from '../types';
+import { parseDuration, validatePath } from '../utils';
+import { TriggerTimeoutError } from '../engine';
+
+const IS_WINDOWS = process.platform === 'win32';
+
+function pathsEqual(a: string, b: string): boolean {
+  return IS_WINDOWS ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+export const FileTrigger: TriggerPlugin = {
+  name: 'file',
+  schema: {
+    description: 'Wait for a file to appear or be modified before the task runs.',
+    fields: {
+      path: {
+        type: 'path',
+        required: true,
+        description: 'Path to the file to watch (relative to workDir or absolute).',
+        placeholder: 'e.g. build/output.json',
+      },
+      timeout: {
+        type: 'duration',
+        description: 'Maximum wait time (e.g. 30s, 5m). Omit or 0 to wait indefinitely.',
+        placeholder: '30s',
+      },
+    },
+  },
+
+  watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
+    const filePath = config.path as string;
+    if (!filePath) throw new Error(`file trigger: "path" is required`);
+
+    const safePath = validatePath(filePath, ctx.workDir);
+    const timeoutMs = config.timeout != null ? parseDuration(String(config.timeout)) : 0;
+
+    // Hoist the async work into a named async function so the Promise
+    // constructor itself is synchronous — avoids the no-async-promise-executor
+    // lint error and ensures exceptions are always propagated via reject().
+    async function start(
+      resolve_p: (value: unknown) => void,
+      reject: (reason?: unknown) => void,
+    ): Promise<void> {
+      if (ctx.signal.aborted) {
+        reject(new Error('Pipeline aborted'));
+        return;
+      }
+
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+
+      // Ensure the parent directory exists so the watcher doesn't fail
+      // with ENOENT for nested paths like `build/output/result.json`.
+      const dir = dirname(safePath);
+      try {
+        await mkdir(dir, { recursive: true });
+      } catch {
+        /* best effort — dir may already exist */
+      }
+
+      // Pass `cwd: dir` so chokidar resolves paths relative to the watched
+      // directory. The 'add'/'change' events will then carry paths relative
+      // to `dir`, which we resolve with `resolve(dir, addedPath)` for an
+      // accurate absolute comparison — fixing the ambiguous process.cwd()
+      // resolution of the previous implementation.
+      const watcher = watch(dir, {
+        ignoreInitial: true,
+        depth: 0,
+        cwd: dir,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+      });
+
+      const cleanup = () => {
+        if (settled) return;
+        settled = true;
+        watcher.close().catch(() => {
+          /* ignore */
+        });
+        if (timer) clearTimeout(timer);
+        ctx.signal.removeEventListener('abort', onAbort);
+      };
+
+      const onAbort = () => {
+        cleanup();
+        reject(new Error('Pipeline aborted'));
+      };
+
+      watcher.on('add', (addedPath: string) => {
+        if (settled) return;
+        if (pathsEqual(resolve(dir, addedPath), safePath)) {
+          cleanup();
+          resolve_p({ path: safePath });
+        }
+      });
+
+      // Also fire on 'change' so that overwriting an existing file is detected.
+      // Without this, upstream tasks that truncate-and-rewrite a file emit only
+      // a 'change' event and the downstream trigger would never resolve.
+      watcher.on('change', (changedPath: string) => {
+        if (settled) return;
+        if (pathsEqual(resolve(dir, changedPath), safePath)) {
+          cleanup();
+          resolve_p({ path: safePath });
+        }
+      });
+
+      watcher.on('error', (err: unknown) => {
+        if (settled) return;
+        cleanup();
+        reject(
+          new Error(
+            `file trigger watch error: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+        );
+      });
+
+      // After the watcher finishes its initial scan, check if the file already exists.
+      // Doing this inside 'ready' eliminates the race window between existence check
+      // and watcher startup, so we neither miss events nor double-resolve.
+      watcher.on('ready', () => {
+        if (settled) return;
+        Bun.file(safePath)
+          .exists()
+          .then((exists) => {
+            if (settled) return;
+            if (exists) {
+              cleanup();
+              resolve_p({ path: safePath });
+            }
+          })
+          .catch((err: unknown) => {
+            if (settled) return;
+            cleanup();
+            reject(
+              new Error(
+                `file trigger existence check failed: ${err instanceof Error ? err.message : String(err)}`,
+              ),
+            );
+          });
+      });
+
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          if (settled) return;
+          cleanup();
+          reject(
+            new TriggerTimeoutError(
+              `file trigger timeout: ${filePath} did not appear within ${config.timeout}`,
+            ),
+          );
+        }, timeoutMs);
+      }
+
+      ctx.signal.addEventListener('abort', onAbort);
+    }
+
+    return new Promise((resolve_p, reject) => {
+      start(resolve_p, reject).catch(reject);
+    });
+  },
+};

package/src/triggers/manual.ts

@@ -1,86 +1,86 @@
-import type { TriggerPlugin, TriggerContext } from '../types';
-import { parseDuration } from '../utils';
-import { TriggerBlockedError, TriggerTimeoutError } from '../engine';
-
-export const ManualTrigger: TriggerPlugin = {
-  name: 'manual',
-  schema: {
-    description: 'Pause the task until a user approves via the approval gateway.',
-    fields: {
-      message: {
-        type: 'string',
-        description: 'Prompt shown to the approver. Defaults to a generic message if empty.',
-        placeholder: 'Confirm deployment to production?',
-      },
-      timeout: {
-        type: 'duration',
-        description: 'Maximum wait time (e.g. 10m). Omit or 0 to wait indefinitely.',
-        placeholder: '10m',
-      },
-    },
-  },
-
-  async watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
-    const message =
-      (config.message as string | undefined) ??
-      `Manual confirmation required for task "${ctx.taskId}"`;
-    const timeoutMs = config.timeout ? parseDuration(config.timeout as string) : 0;
-    const metadata =
-      config.metadata && typeof config.metadata === 'object'
-        ? (config.metadata as Record<string, unknown>)
-        : undefined;
-
-    const decisionPromise = ctx.approvalGateway.request({
-      taskId: ctx.taskId,
-      trackId: ctx.trackId,
-      message,
-      timeoutMs,
-      metadata,
-    });
-
-    // Wire AbortSignal → try to resolve this specific request as aborted.
-    // We can't directly cancel via the gateway (no id yet at .request() call site),
-    // so instead we race against an abort promise and let engine status logic
-    // fall back to pipelineAborted → skipped. abortAll() on gateway still runs
-    // from engine shutdown path to clean up any truly-pending entries.
-    const onAbort = () => {};
-    const abortPromise = new Promise<never>((_, reject) => {
-      if (ctx.signal.aborted) {
-        reject(new Error('Pipeline aborted'));
-        return;
-      }
-      const handler = () => reject(new Error('Pipeline aborted'));
-      // Store reference so we can remove it after the race settles.
-      (onAbort as { handler?: () => void }).handler = handler;
-      ctx.signal.addEventListener('abort', handler, { once: true });
-    });
-
-    let decision: Awaited<typeof decisionPromise>;
-    try {
-      decision = await Promise.race([decisionPromise, abortPromise]);
-    } finally {
-      // Clean up the abort listener to prevent leaking on normal completion.
-      const handler = (onAbort as { handler?: () => void }).handler;
-      if (handler) ctx.signal.removeEventListener('abort', handler);
-    }
-
-    switch (decision.outcome) {
-      case 'approved':
-        return { confirmed: true, approvalId: decision.approvalId, actor: decision.actor };
-      case 'rejected':
-        // A7: Use typed error for proper classification in the engine.
-        throw new TriggerBlockedError(
-          `Manual trigger rejected by ${decision.actor ?? 'user'}` +
-            (decision.reason ? `: ${decision.reason}` : ''),
-        );
-      case 'timeout':
-        throw new TriggerTimeoutError(
-          `Manual trigger timeout: ${decision.reason ?? 'no decision made'}`,
-        );
-      case 'aborted':
-        throw new TriggerBlockedError(
-          `Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`,
-        );
-    }
-  },
-};
+import type { TriggerPlugin, TriggerContext } from '../types';
+import { parseDuration } from '../utils';
+import { TriggerBlockedError, TriggerTimeoutError } from '../engine';
+
+export const ManualTrigger: TriggerPlugin = {
+  name: 'manual',
+  schema: {
+    description: 'Pause the task until a user approves via the approval gateway.',
+    fields: {
+      message: {
+        type: 'string',
+        description: 'Prompt shown to the approver. Defaults to a generic message if empty.',
+        placeholder: 'Confirm deployment to production?',
+      },
+      timeout: {
+        type: 'duration',
+        description: 'Maximum wait time (e.g. 10m). Omit or 0 to wait indefinitely.',
+        placeholder: '10m',
+      },
+    },
+  },
+
+  async watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
+    const message =
+      (config.message as string | undefined) ??
+      `Manual confirmation required for task "${ctx.taskId}"`;
+    const timeoutMs = config.timeout ? parseDuration(config.timeout as string) : 0;
+    const metadata =
+      config.metadata && typeof config.metadata === 'object'
+        ? (config.metadata as Record<string, unknown>)
+        : undefined;
+
+    const decisionPromise = ctx.approvalGateway.request({
+      taskId: ctx.taskId,
+      trackId: ctx.trackId,
+      message,
+      timeoutMs,
+      metadata,
+    });
+
+    // Wire AbortSignal → try to resolve this specific request as aborted.
+    // We can't directly cancel via the gateway (no id yet at .request() call site),
+    // so instead we race against an abort promise and let engine status logic
+    // fall back to pipelineAborted → skipped. abortAll() on gateway still runs
+    // from engine shutdown path to clean up any truly-pending entries.
+    const onAbort = () => {};
+    const abortPromise = new Promise<never>((_, reject) => {
+      if (ctx.signal.aborted) {
+        reject(new Error('Pipeline aborted'));
+        return;
+      }
+      const handler = () => reject(new Error('Pipeline aborted'));
+      // Store reference so we can remove it after the race settles.
+      (onAbort as { handler?: () => void }).handler = handler;
+      ctx.signal.addEventListener('abort', handler, { once: true });
+    });
+
+    let decision: Awaited<typeof decisionPromise>;
+    try {
+      decision = await Promise.race([decisionPromise, abortPromise]);
+    } finally {
+      // Clean up the abort listener to prevent leaking on normal completion.
+      const handler = (onAbort as { handler?: () => void }).handler;
+      if (handler) ctx.signal.removeEventListener('abort', handler);
+    }
+
+    switch (decision.outcome) {
+      case 'approved':
+        return { confirmed: true, approvalId: decision.approvalId, actor: decision.actor };
+      case 'rejected':
+        // A7: Use typed error for proper classification in the engine.
+        throw new TriggerBlockedError(
+          `Manual trigger rejected by ${decision.actor ?? 'user'}` +
+            (decision.reason ? `: ${decision.reason}` : ''),
+        );
+      case 'timeout':
+        throw new TriggerTimeoutError(
+          `Manual trigger timeout: ${decision.reason ?? 'no decision made'}`,
+        );
+      case 'aborted':
+        throw new TriggerBlockedError(
+          `Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`,
+        );
+    }
+  },
+};

package/src/types.ts

@@ -1,18 +1,18 @@
-// ═══ Engine-facing type surface ═══
-//
-// All type definitions live in the shared `@tagma/types` workspace package
-// so that plugins under plugins/* can depend on the same types without
-// reaching into the engine's internals. This file re-exports everything
-// and adds runtime-only values (constants) that plugins don't need.
-
-export * from '@tagma/types';
-
-import type { Permissions } from '@tagma/types';
-
-// ═══ Runtime Constants ═══
-
-export const DEFAULT_PERMISSIONS: Permissions = {
-  read: true,
-  write: false,
-  execute: false,
-};
+// ═══ Engine-facing type surface ═══
+//
+// All type definitions live in the shared `@tagma/types` workspace package
+// so that plugins under plugins/* can depend on the same types without
+// reaching into the engine's internals. This file re-exports everything
+// and adds runtime-only values (constants) that plugins don't need.
+
+export * from '@tagma/types';
+
+import type { Permissions } from '@tagma/types';
+
+// ═══ Runtime Constants ═══
+
+export const DEFAULT_PERMISSIONS: Permissions = {
+  read: true,
+  write: false,
+  execute: false,
+};