@tagma/sdk 0.5.2 → 0.6.0

package/src/task-ref.ts

@@ -1,120 +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 };
-}
+// ═══ 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);
+    });
+  },
+};