@tagma/sdk 0.4.10 → 0.4.12

package/src/triggers/file.ts

@@ -1,129 +1,145 @@
-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;
-
-    return new Promise(async (resolve_p, reject) => {
-      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 */ }
-
-      const watcher = watch(dir, {
-        ignoreInitial: true,
-        depth: 0,
-        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(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(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);
-    });
-  },
-};
+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/utils.ts

@@ -1,4 +1,5 @@
-import { resolve, relative } from 'path';
+import { resolve, relative, parse as parsePath } from 'path';
+import { realpathSync, lstatSync, existsSync } from 'fs';
 import { randomBytes } from 'crypto';
 
 const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
@@ -21,15 +22,65 @@ export function parseDuration(input: string): number {
 
 export function validatePath(filePath: string, projectRoot: string): string {
   const resolved = resolve(projectRoot, filePath);
-  const rel = relative(projectRoot, resolved);
 
-  if (rel.startsWith('..') || rel.startsWith('/') || /^[a-zA-Z]:/.test(rel)) {
+  // D2: Cross-drive check (Windows) — path.relative('C:\\root', 'D:\\x') returns
+  // 'D:\\x' which does NOT start with '..', so a pure relative check would wrongly
+  // allow cross-drive paths. Reject them explicitly before any further comparison.
+  if (parsePath(projectRoot).root !== parsePath(resolved).root) {
+    throw new Error(
+      `Security: path "${filePath}" is on a different drive than the project root "${projectRoot}".`
+    );
+  }
+
+  const rel = relative(projectRoot, resolved);
+  if (rel.startsWith('..') || rel.startsWith('/')) {
     throw new Error(
       `Security: path "${filePath}" escapes project root. ` +
       `All file references must be within "${projectRoot}".`
     );
   }
 
+  // D1: Resolve symlinks and re-validate so a symlink whose string path is
+  // inside the project root but whose target lies outside is rejected.
+  // Only resolve if the path exists on disk; at parse time the file may not
+  // yet exist (e.g. a future output path), so we skip realpath for absent paths.
+  if (existsSync(resolved)) {
+    // Reject the entry outright if it is itself a symlink — callers that want
+    // to allow symlinks within the tree can pass pre-resolved paths.
+    try {
+      const stat = lstatSync(resolved);
+      if (stat.isSymbolicLink()) {
+        throw new Error(
+          `Security: path "${filePath}" is a symbolic link. Symbolic links are not allowed within the project root.`
+        );
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    }
+
+    // Also verify the real (fully resolved) path stays within the project root.
+    let real: string;
+    try {
+      real = realpathSync.native(resolved);
+    } catch {
+      real = resolved; // path vanished between existsSync and realpathSync — skip
+    }
+    const realRoot = (() => {
+      try { return realpathSync.native(projectRoot); } catch { return projectRoot; }
+    })();
+    if (parsePath(realRoot).root !== parsePath(real).root) {
+      throw new Error(
+        `Security: resolved path "${real}" is on a different drive than the project root "${realRoot}".`
+      );
+    }
+    const realRel = relative(realRoot, real);
+    if (realRel.startsWith('..') || realRel.startsWith('/')) {
+      throw new Error(
+        `Security: path "${filePath}" resolves via symlink to "${real}" which escapes project root "${realRoot}".`
+      );
+    }
+  }
+
   return resolved;
 }
 

package/src/validate-raw.ts

@@ -13,6 +13,15 @@ function isValidDuration(input: string): boolean {
   return DURATION_RE.test(input.trim());
 }
 
+// D8: IDs may only contain letters, digits, underscores, and hyphens, and must
+// start with a letter or underscore. Dots are explicitly forbidden because the
+// engine uses "trackId.taskId" as the qualified separator — a dot in either
+// part creates an ambiguous qualified ID and breaks resolveRef.
+const ID_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function isValidId(id: string): boolean {
+  return ID_RE.test(id);
+}
+
 const VALID_ON_FAILURE = new Set(['skip_downstream', 'stop_all', 'ignore']);
 const VALID_REASONING_EFFORT = new Set(['low', 'medium', 'high']);
 
@@ -128,6 +137,11 @@ export function validateRaw(
 
     if (!track.id?.trim()) {
       errors.push({ path: `${trackPath}.id`, message: 'Track id is required' });
+    } else if (!isValidId(track.id)) {
+      errors.push({
+        path: `${trackPath}.id`,
+        message: `Track id "${track.id}" contains invalid characters. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ (no dots, spaces, or special chars).`,
+      });
     } else if (seenTrackIds.has(track.id)) {
       errors.push({ path: `${trackPath}.id`, message: `Duplicate track id "${track.id}"` });
     } else {
@@ -175,6 +189,12 @@ export function validateRaw(
         continue; // Can't check further without an id
       }
 
+      if (!isValidId(task.id)) {
+        errors.push({
+          path: `${taskPath}.id`,
+          message: `Task id "${task.id}" contains invalid characters. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ (no dots, spaces, or special chars).`,
+        });
+      }
       if (seenTaskIds.has(task.id)) {
         errors.push({ path: taskPath, message: `Duplicate task id "${task.id}" in track "${track.id}"` });
       }