@tagma/sdk 0.1.3 → 0.1.5

package/src/sdk.ts

@@ -5,10 +5,32 @@
 
 // ── Core engine ──
 export { runPipeline } from './engine';
-export type { EngineResult, RunPipelineOptions } from './engine';
+export type { EngineResult, RunPipelineOptions, PipelineEvent } from './engine';
 
-// ── Schema: parse / resolve / load ──
-export { parseYaml, resolveConfig, expandTemplates, loadPipeline } from './schema';
+// ── Pipeline runner (multi-pipeline lifecycle management) ──
+export { PipelineRunner } from './pipeline-runner';
+export type { PipelineRunnerStatus } from './pipeline-runner';
+
+// ── Raw config CRUD (visual editor / YAML sync) ──
+export {
+  createEmptyPipeline,
+  setPipelineField,
+  upsertTrack,
+  removeTrack,
+  moveTrack,
+  updateTrack,
+  upsertTask,
+  removeTask,
+  moveTask,
+  transferTask,
+} from './config-ops';
+
+// ── Raw config validation (real-time feedback) ──
+export { validateRaw } from './validate-raw';
+export type { ValidationError } from './validate-raw';
+
+// ── Schema: parse / resolve / load / serialize / validate ──
+export { parseYaml, resolveConfig, expandTemplates, loadPipeline, serializePipeline, deresolvePipeline, validateConfig } from './schema';
 
 // ── DAG ──
 export { buildDag } from './dag';

package/src/triggers/file.ts

@@ -1,94 +1,94 @@
-import { watch } from 'chokidar';
-import { resolve, dirname } from 'path';
-import type { TriggerPlugin, TriggerContext } from '../types';
-import { parseDuration, validatePath } from '../utils';
-
-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',
-
-  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((resolve_p, reject) => {
-      if (ctx.signal.aborted) {
-        reject(new Error('Pipeline aborted'));
-        return;
-      }
-
-      let settled = false;
-      let timer: ReturnType<typeof setTimeout> | null = null;
-
-      const dir = dirname(safePath);
-      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 });
-        }
-      });
-
-      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 Error(`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 type { TriggerPlugin, TriggerContext } from '../types';
+import { parseDuration, validatePath } from '../utils';
+
+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',
+
+  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((resolve_p, reject) => {
+      if (ctx.signal.aborted) {
+        reject(new Error('Pipeline aborted'));
+        return;
+      }
+
+      let settled = false;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+
+      const dir = dirname(safePath);
+      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 });
+        }
+      });
+
+      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 Error(`file trigger timeout: ${filePath} did not appear within ${config.timeout}`));
+        }, timeoutMs);
+      }
+
+      ctx.signal.addEventListener('abort', onAbort);
+    });
+  },
+};

package/src/triggers/manual.ts

@@ -1,61 +1,61 @@
-import type { TriggerPlugin, TriggerContext } from '../types';
-import { parseDuration } from '../utils';
-
-export const ManualTrigger: TriggerPlugin = {
-  name: 'manual',
-
-  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 options = Array.isArray(config.options)
-      ? (config.options as unknown[]).map(String)
-      : undefined;
-    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,
-      options,
-      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 abortPromise = new Promise<never>((_, reject) => {
-      if (ctx.signal.aborted) {
-        reject(new Error('Pipeline aborted'));
-        return;
-      }
-      ctx.signal.addEventListener(
-        'abort',
-        () => reject(new Error('Pipeline aborted')),
-        { once: true },
-      );
-    });
-
-    const decision = await Promise.race([decisionPromise, abortPromise]);
-
-    switch (decision.outcome) {
-      case 'approved':
-        return { confirmed: true, approvalId: decision.approvalId, choice: decision.choice, actor: decision.actor };
-      case 'rejected':
-        throw new Error(
-          `Manual trigger rejected by ${decision.actor ?? 'user'}` +
-            (decision.reason ? `: ${decision.reason}` : ''),
-        );
-      case 'timeout':
-        throw new Error(`Manual trigger timeout: ${decision.reason ?? 'no decision made'}`);
-      case 'aborted':
-        throw new Error(`Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`);
-    }
-  },
-};
+import type { TriggerPlugin, TriggerContext } from '../types';
+import { parseDuration } from '../utils';
+
+export const ManualTrigger: TriggerPlugin = {
+  name: 'manual',
+
+  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 options = Array.isArray(config.options)
+      ? (config.options as unknown[]).map(String)
+      : undefined;
+    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,
+      options,
+      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 abortPromise = new Promise<never>((_, reject) => {
+      if (ctx.signal.aborted) {
+        reject(new Error('Pipeline aborted'));
+        return;
+      }
+      ctx.signal.addEventListener(
+        'abort',
+        () => reject(new Error('Pipeline aborted')),
+        { once: true },
+      );
+    });
+
+    const decision = await Promise.race([decisionPromise, abortPromise]);
+
+    switch (decision.outcome) {
+      case 'approved':
+        return { confirmed: true, approvalId: decision.approvalId, choice: decision.choice, actor: decision.actor };
+      case 'rejected':
+        throw new Error(
+          `Manual trigger rejected by ${decision.actor ?? 'user'}` +
+            (decision.reason ? `: ${decision.reason}` : ''),
+        );
+      case 'timeout':
+        throw new Error(`Manual trigger timeout: ${decision.reason ?? 'no decision made'}`);
+      case 'aborted':
+        throw new Error(`Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`);
+    }
+  },
+};

package/src/utils.ts

@@ -1,147 +1,147 @@
-import { resolve, relative } from 'path';
-
-const DURATION_RE = /^(\d+(?:\.\d+)?)\s*(s|m|h)$/;
-
-export function parseDuration(input: string): number {
-  const match = DURATION_RE.exec(input.trim());
-  if (!match) {
-    throw new Error(`Invalid duration format: "${input}". Expected format: <number>(s|m|h)`);
-  }
-  const value = parseFloat(match[1]);
-  const unit = match[2];
-  switch (unit) {
-    case 's': return value * 1000;
-    case 'm': return value * 60_000;
-    case 'h': return value * 3_600_000;
-    default:  throw new Error(`Unknown duration unit: "${unit}"`);
-  }
-}
-
-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)) {
-    throw new Error(
-      `Security: path "${filePath}" escapes project root. ` +
-      `All file references must be within "${projectRoot}".`
-    );
-  }
-
-  return resolved;
-}
-
-const SHELL_META_CHARS = /[;&|$`\\!><()\[\]{}*?#~]/;
-
-export function validatePathParam(filePath: string): void {
-  if (filePath.includes('..')) {
-    throw new Error(`Template param type=path: ".." traversal not allowed in "${filePath}"`);
-  }
-  if (resolve(filePath) === filePath) {
-    throw new Error(`Template param type=path: absolute path not allowed: "${filePath}"`);
-  }
-  if (SHELL_META_CHARS.test(filePath)) {
-    throw new Error(`Template param type=path: shell metacharacters not allowed in "${filePath}"`);
-  }
-}
-
-let runCounter = 0;
-
-export function generateRunId(): string {
-  const ts = Date.now().toString(36);
-  const seq = (runCounter++).toString(36);
-  return `run_${ts}_${seq}`;
-}
-
-export function truncateForName(text: string, maxLen = 40): string {
-  const first = text.split('\n')[0].trim();
-  return first.length > maxLen ? first.slice(0, maxLen) + '...' : first;
-}
-
-export function nowISO(): string {
-  return new Date().toISOString();
-}
-
-// ═══ Platform-aware shell ═══
-//
-// Resolution order:
-//   1. Env override: PIPELINE_SHELL="bash" or PIPELINE_SHELL="cmd" etc.
-//   2. Windows: prefer sh (Git Bash / MSYS2) if on PATH, fall back to cmd.exe
-//   3. Unix: sh
-//
-// Resolution is cached once on first call to avoid repeated PATH lookups.
-
-const IS_WINDOWS = process.platform === 'win32';
-
-type ShellKind = 'sh' | 'bash' | 'cmd' | 'powershell';
-let resolvedShell: { kind: ShellKind; path: string } | null = null;
-
-function detectShell(): { kind: ShellKind; path: string } {
-  // Env override takes precedence
-  const override = process.env.PIPELINE_SHELL;
-  if (override) {
-    const kind = override as ShellKind;
-    return { kind, path: override };
-  }
-
-  if (!IS_WINDOWS) {
-    return { kind: 'sh', path: 'sh' };
-  }
-
-  // Windows: probe PATH for sh (bundled with Git for Windows / MSYS2)
-  const pathEnv = process.env.PATH ?? '';
-  const pathExt = (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';');
-  const dirs = pathEnv.split(';').filter(Boolean);
-
-  for (const dir of dirs) {
-    for (const ext of ['', ...pathExt]) {
-      const candidate = `${dir}\\sh${ext}`;
-      try {
-        if (Bun.file(candidate).size > 0) {
-          return { kind: 'sh', path: candidate };
-        }
-      } catch { /* ignore */ }
-    }
-  }
-
-  // Fallback: cmd.exe (always present on Windows)
-  const systemRoot = process.env.SystemRoot ?? 'C:\\Windows';
-  return { kind: 'cmd', path: `${systemRoot}\\System32\\cmd.exe` };
-}
-
-function getShell(): { kind: ShellKind; path: string } {
-  if (!resolvedShell) resolvedShell = detectShell();
-  return resolvedShell;
-}
-
-export function shellArgs(command: string): readonly string[] {
-  const sh = getShell();
-  if (sh.kind === 'cmd') {
-    return [sh.path, '/c', command];
-  }
-  if (sh.kind === 'powershell') {
-    return [sh.path, '-Command', command];
-  }
-  // sh or bash
-  return [sh.path, '-c', command];
-}
-
-/** Quote a single argument for inclusion in a shell command string. */
-function quoteArg(arg: string): string {
-  if (!/[\s"'\\<>|&;`$!^%]/.test(arg)) return arg;
-  // Double-quote and escape embedded double quotes + backslashes
-  return '"' + arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
-}
-
-/**
- * Convert an args array to shell-wrapped args suitable for Bun.spawn.
- * Each arg is quoted as needed, then joined and passed through shellArgs.
- */
-export function shellArgsFromArray(args: readonly string[]): readonly string[] {
-  return shellArgs(args.map(quoteArg).join(' '));
-}
-
-// For tests: allow resetting the cached shell detection
-export function _resetShellCache(): void {
-  resolvedShell = null;
-}
+import { resolve, relative } from 'path';
+
+const DURATION_RE = /^(\d+(?:\.\d+)?)\s*(s|m|h)$/;
+
+export function parseDuration(input: string): number {
+  const match = DURATION_RE.exec(input.trim());
+  if (!match) {
+    throw new Error(`Invalid duration format: "${input}". Expected format: <number>(s|m|h)`);
+  }
+  const value = parseFloat(match[1]);
+  const unit = match[2];
+  switch (unit) {
+    case 's': return value * 1000;
+    case 'm': return value * 60_000;
+    case 'h': return value * 3_600_000;
+    default:  throw new Error(`Unknown duration unit: "${unit}"`);
+  }
+}
+
+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)) {
+    throw new Error(
+      `Security: path "${filePath}" escapes project root. ` +
+      `All file references must be within "${projectRoot}".`
+    );
+  }
+
+  return resolved;
+}
+
+const SHELL_META_CHARS = /[;&|$`\\!><()\[\]{}*?#~]/;
+
+export function validatePathParam(filePath: string): void {
+  if (filePath.includes('..')) {
+    throw new Error(`Template param type=path: ".." traversal not allowed in "${filePath}"`);
+  }
+  if (resolve(filePath) === filePath) {
+    throw new Error(`Template param type=path: absolute path not allowed: "${filePath}"`);
+  }
+  if (SHELL_META_CHARS.test(filePath)) {
+    throw new Error(`Template param type=path: shell metacharacters not allowed in "${filePath}"`);
+  }
+}
+
+let runCounter = 0;
+
+export function generateRunId(): string {
+  const ts = Date.now().toString(36);
+  const seq = (runCounter++).toString(36);
+  return `run_${ts}_${seq}`;
+}
+
+export function truncateForName(text: string, maxLen = 40): string {
+  const first = text.split('\n')[0].trim();
+  return first.length > maxLen ? first.slice(0, maxLen) + '...' : first;
+}
+
+export function nowISO(): string {
+  return new Date().toISOString();
+}
+
+// ═══ Platform-aware shell ═══
+//
+// Resolution order:
+//   1. Env override: PIPELINE_SHELL="bash" or PIPELINE_SHELL="cmd" etc.
+//   2. Windows: prefer sh (Git Bash / MSYS2) if on PATH, fall back to cmd.exe
+//   3. Unix: sh
+//
+// Resolution is cached once on first call to avoid repeated PATH lookups.
+
+const IS_WINDOWS = process.platform === 'win32';
+
+type ShellKind = 'sh' | 'bash' | 'cmd' | 'powershell';
+let resolvedShell: { kind: ShellKind; path: string } | null = null;
+
+function detectShell(): { kind: ShellKind; path: string } {
+  // Env override takes precedence
+  const override = process.env.PIPELINE_SHELL;
+  if (override) {
+    const kind = override as ShellKind;
+    return { kind, path: override };
+  }
+
+  if (!IS_WINDOWS) {
+    return { kind: 'sh', path: 'sh' };
+  }
+
+  // Windows: probe PATH for sh (bundled with Git for Windows / MSYS2)
+  const pathEnv = process.env.PATH ?? '';
+  const pathExt = (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';');
+  const dirs = pathEnv.split(';').filter(Boolean);
+
+  for (const dir of dirs) {
+    for (const ext of ['', ...pathExt]) {
+      const candidate = `${dir}\\sh${ext}`;
+      try {
+        if (Bun.file(candidate).size > 0) {
+          return { kind: 'sh', path: candidate };
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Fallback: cmd.exe (always present on Windows)
+  const systemRoot = process.env.SystemRoot ?? 'C:\\Windows';
+  return { kind: 'cmd', path: `${systemRoot}\\System32\\cmd.exe` };
+}
+
+function getShell(): { kind: ShellKind; path: string } {
+  if (!resolvedShell) resolvedShell = detectShell();
+  return resolvedShell;
+}
+
+export function shellArgs(command: string): readonly string[] {
+  const sh = getShell();
+  if (sh.kind === 'cmd') {
+    return [sh.path, '/c', command];
+  }
+  if (sh.kind === 'powershell') {
+    return [sh.path, '-Command', command];
+  }
+  // sh or bash
+  return [sh.path, '-c', command];
+}
+
+/** Quote a single argument for inclusion in a shell command string. */
+function quoteArg(arg: string): string {
+  if (!/[\s"'\\<>|&;`$!^%]/.test(arg)) return arg;
+  // Double-quote and escape embedded double quotes + backslashes
+  return '"' + arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+/**
+ * Convert an args array to shell-wrapped args suitable for Bun.spawn.
+ * Each arg is quoted as needed, then joined and passed through shellArgs.
+ */
+export function shellArgsFromArray(args: readonly string[]): readonly string[] {
+  return shellArgs(args.map(quoteArg).join(' '));
+}
+
+// For tests: allow resetting the cached shell detection
+export function _resetShellCache(): void {
+  resolvedShell = null;
+}