@tagma/sdk 0.1.2

package/src/schema.ts

@@ -0,0 +1,260 @@
+import yaml from 'js-yaml';
+import { resolve } from 'path';
+import type {
+  PipelineConfig, RawPipelineConfig, RawTrackConfig, RawTaskConfig,
+  TrackConfig, TaskConfig, Permissions, MiddlewareConfig,
+  TemplateConfig, TemplateParamDef,
+} from './types';
+import { truncateForName, validatePathParam } from './utils';
+import { DEFAULT_PERMISSIONS } from './types';
+
+// ═══ YAML Parsing ═══
+
+export function parseYaml(content: string): RawPipelineConfig {
+  const doc = yaml.load(content) as { pipeline?: RawPipelineConfig };
+  if (!doc?.pipeline) {
+    throw new Error('YAML must contain a top-level "pipeline" key');
+  }
+  const p = doc.pipeline;
+  if (!p.name) throw new Error('pipeline.name is required');
+  if (!p.tracks || p.tracks.length === 0) throw new Error('pipeline.tracks must be non-empty');
+
+  for (const track of p.tracks) {
+    validateRawTrack(track);
+  }
+  return p;
+}
+
+function validateRawTrack(track: RawTrackConfig): void {
+  if (!track.id) throw new Error('track.id is required');
+  if (!track.name) throw new Error(`track "${track.id}": name is required`);
+  if (!track.tasks || track.tasks.length === 0) {
+    throw new Error(`track "${track.id}": tasks must be non-empty`);
+  }
+  for (const task of track.tasks) {
+    validateRawTask(task, track.id);
+  }
+}
+
+function validateRawTask(task: RawTaskConfig, trackId: string): void {
+  if (!task.id) throw new Error(`track "${trackId}": task.id is required`);
+  if (task.use) return; // template usage, validated later
+
+  const hasPrompt = typeof task.prompt === 'string' && task.prompt.length > 0;
+  const hasCommand = typeof task.command === 'string' && task.command.length > 0;
+  if (!hasPrompt && !hasCommand) {
+    throw new Error(`task "${task.id}": must have either "prompt" or "command"`);
+  }
+  if (hasPrompt && hasCommand) {
+    throw new Error(`task "${task.id}": cannot have both "prompt" and "command"`);
+  }
+}
+
+// ═══ Template Expansion ═══
+
+export async function expandTemplates(
+  tasks: readonly RawTaskConfig[],
+  instancePrefix: string,
+): Promise<RawTaskConfig[]> {
+  const result: RawTaskConfig[] = [];
+
+  for (const task of tasks) {
+    if (!task.use) {
+      result.push(task);
+      continue;
+    }
+
+    const template = await loadTemplate(task.use);
+    const params = resolveTemplateParams(template, task.with ?? {}, task.id);
+    const expanded = expandTemplateTask(template, params, task.id, instancePrefix);
+    result.push(...expanded);
+  }
+
+  return result;
+}
+
+async function loadTemplate(ref: string): Promise<TemplateConfig> {
+  // Strip version suffix for import
+  const moduleName = ref.replace(/@v\d+$/, '');
+  try {
+    const mod = await import(moduleName);
+    // Expect the module to export a template.yaml content or parsed object
+    if (mod.template) return mod.template as TemplateConfig;
+
+    // Try loading template.yaml from the package
+    const pkgPath = require.resolve(`${moduleName}/template.yaml`);
+    const content = await Bun.file(pkgPath).text();
+    const doc = yaml.load(content) as { template: TemplateConfig };
+    return doc.template;
+  } catch {
+    throw new Error(`Failed to load template: "${ref}". Is the package installed?`);
+  }
+}
+
+function resolveTemplateParams(
+  template: TemplateConfig,
+  provided: Record<string, unknown>,
+  instanceId: string,
+): Record<string, unknown> {
+  const params: Record<string, unknown> = {};
+  const defs = template.params ?? {};
+
+  for (const [key, def] of Object.entries(defs)) {
+    const value = provided[key] ?? def.default;
+    if (value === undefined) {
+      throw new Error(`Template "${template.name}" instance "${instanceId}": missing required param "${key}"`);
+    }
+    validateParamType(key, value, def, template.name, instanceId);
+    params[key] = value;
+  }
+
+  // Warn about unknown params
+  for (const key of Object.keys(provided)) {
+    if (!(key in defs)) {
+      console.warn(`Template "${template.name}" instance "${instanceId}": unknown param "${key}"`);
+    }
+  }
+
+  return params;
+}
+
+function validateParamType(
+  key: string, value: unknown, def: TemplateParamDef,
+  templateName: string, instanceId: string,
+): void {
+  const ctx = `Template "${templateName}" instance "${instanceId}" param "${key}"`;
+  const ptype = def.type ?? 'string';
+
+  switch (ptype) {
+    case 'string':
+      if (typeof value !== 'string') throw new Error(`${ctx}: expected string, got ${typeof value}`);
+      break;
+    case 'path':
+      if (typeof value !== 'string') throw new Error(`${ctx}: expected path string, got ${typeof value}`);
+      validatePathParam(value);
+      break;
+    case 'enum':
+      if (!def.enum?.includes(value as string)) {
+        throw new Error(`${ctx}: value "${value}" not in allowed values [${def.enum?.join(', ')}]`);
+      }
+      break;
+    case 'number':
+      if (typeof value !== 'number') throw new Error(`${ctx}: expected number, got ${typeof value}`);
+      if (def.min !== undefined && value < def.min) throw new Error(`${ctx}: ${value} < min ${def.min}`);
+      if (def.max !== undefined && value > def.max) throw new Error(`${ctx}: ${value} > max ${def.max}`);
+      break;
+  }
+}
+
+function expandTemplateTask(
+  template: TemplateConfig,
+  params: Record<string, unknown>,
+  instanceId: string,
+  instancePrefix: string,
+): RawTaskConfig[] {
+  return template.tasks.map(task => {
+    const prefixedId = `${instanceId}.${task.id}`;
+
+    // Replace ${{ params.xxx }} in string fields
+    const interpolate = (s: string): string =>
+      s.replace(/\$\{\{\s*params\.(\w+)\s*\}\}/g, (_, key) => String(params[key] ?? ''));
+
+    const newTask: Record<string, unknown> = { ...task, id: prefixedId };
+
+    // Interpolate string fields
+    if (task.prompt) newTask.prompt = interpolate(task.prompt);
+    if (task.command) newTask.command = interpolate(task.command);
+
+    // Namespace depends_on
+    if (task.depends_on) {
+      newTask.depends_on = task.depends_on.map(dep => `${instanceId}.${dep}`);
+    }
+
+    // Namespace continue_from
+    if (task.continue_from) {
+      newTask.continue_from = `${instanceId}.${task.continue_from}`;
+    }
+
+    // Rewrite output path to instance namespace
+    if (task.output) {
+      const original = interpolate(task.output);
+      newTask.output = original.replace('./tmp/', `./tmp/${instanceId}/`);
+    }
+
+    return newTask as unknown as RawTaskConfig;
+  });
+}
+
+// ═══ Config Inheritance Resolution ═══
+
+export function resolveConfig(raw: RawPipelineConfig, workDir: string): PipelineConfig {
+  const tracks: TrackConfig[] = raw.tracks.map(rawTrack => {
+    const trackDriver = rawTrack.driver ?? raw.driver;
+    const trackCwd = rawTrack.cwd ? resolve(workDir, rawTrack.cwd) : workDir;
+
+    const tasks: TaskConfig[] = rawTrack.tasks.map(rawTask => {
+      const name = rawTask.name
+        ?? (rawTask.prompt ? truncateForName(rawTask.prompt) : rawTask.command ?? rawTask.id);
+
+      return {
+        id: rawTask.id,
+        name,
+        prompt: rawTask.prompt,
+        command: rawTask.command,
+        depends_on: rawTask.depends_on,
+        trigger: rawTask.trigger,
+        continue_from: rawTask.continue_from,
+        output: rawTask.output,
+        // Inheritance: Task > Track
+        model_tier: rawTask.model_tier ?? rawTrack.model_tier ?? 'medium',
+        permissions: rawTask.permissions ?? rawTrack.permissions ?? DEFAULT_PERMISSIONS,
+        driver: rawTask.driver ?? trackDriver ?? 'claude-code',
+        timeout: rawTask.timeout,
+        // Middleware: Task-level overrides Track (including [] to disable)
+        middlewares: rawTask.middlewares !== undefined ? rawTask.middlewares : rawTrack.middlewares,
+        completion: rawTask.completion,
+        agent_profile: rawTask.agent_profile ?? rawTrack.agent_profile,
+        cwd: rawTask.cwd ? resolve(workDir, rawTask.cwd) : trackCwd,
+      };
+    });
+
+    return {
+      id: rawTrack.id,
+      name: rawTrack.name,
+      color: rawTrack.color,
+      agent_profile: rawTrack.agent_profile,
+      model_tier: rawTrack.model_tier ?? 'medium',
+      permissions: rawTrack.permissions ?? DEFAULT_PERMISSIONS,
+      driver: trackDriver ?? 'claude-code',
+      cwd: trackCwd,
+      middlewares: rawTrack.middlewares,
+      on_failure: rawTrack.on_failure ?? 'skip_downstream',
+      tasks,
+    };
+  });
+
+  return {
+    name: raw.name,
+    driver: raw.driver,
+    timeout: raw.timeout,
+    plugins: raw.plugins,
+    hooks: raw.hooks,
+    tracks,
+  };
+}
+
+// ═══ Full Parse Pipeline ═══
+
+export async function loadPipeline(yamlContent: string, workDir: string): Promise<PipelineConfig> {
+  const raw = parseYaml(yamlContent);
+
+  // Expand templates in each track
+  const expandedTracks: RawTrackConfig[] = [];
+  for (const track of raw.tracks) {
+    const expandedTasks = await expandTemplates(track.tasks, track.id);
+    expandedTracks.push({ ...track, tasks: expandedTasks });
+  }
+
+  const expandedRaw: RawPipelineConfig = { ...raw, tracks: expandedTracks };
+  return resolveConfig(expandedRaw, workDir);
+}

package/src/sdk.ts

@@ -0,0 +1,48 @@
+// ═══ tagma-sdk public API ═══
+//
+// This is the SDK entry point. Import from here, not from internal modules.
+// The CLI (src/index.ts in the CLI project) also imports from here.
+
+// ── Core engine ──
+export { runPipeline } from './engine';
+export type { EngineResult, RunPipelineOptions } from './engine';
+
+// ── Schema: parse / resolve / load ──
+export { parseYaml, resolveConfig, expandTemplates, loadPipeline } from './schema';
+
+// ── DAG ──
+export { buildDag } from './dag';
+export type { DagNode, Dag } from './dag';
+
+// ── Plugin registry ──
+export { bootstrapBuiltins } from './bootstrap';
+export { loadPlugins, registerPlugin, getHandler, hasHandler, listRegistered } from './registry';
+
+// ── Approval gateway ──
+export { InMemoryApprovalGateway } from './approval';
+export type {
+  ApprovalGateway,
+  ApprovalRequest,
+  ApprovalDecision,
+  ApprovalOutcome,
+  ApprovalEvent,
+  ApprovalListener,
+} from './approval';
+
+// ── Approval adapters ──
+export { attachStdinApprovalAdapter } from './adapters/stdin-approval';
+export type { StdinApprovalAdapter } from './adapters/stdin-approval';
+export { attachWebSocketApprovalAdapter } from './adapters/websocket-approval';
+export type { WebSocketApprovalAdapter, WebSocketApprovalAdapterOptions } from './adapters/websocket-approval';
+
+// ── Logger ──
+export { Logger, tailLines, clip } from './logger';
+
+// ── Hook context types (useful for frontend display) ──
+export type { HookResult, PipelineInfo, TrackInfo, TaskInfo } from './hooks';
+
+// ── Utils (public subset) ──
+export { parseDuration, validatePath, generateRunId, nowISO, truncateForName } from './utils';
+
+// ── All types from @tagma/types + runtime constants ──
+export * from './types';

package/src/triggers/file.ts

@@ -0,0 +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);
+    });
+  },
+};

package/src/triggers/manual.ts

@@ -0,0 +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'}`);
+    }
+  },
+};

package/src/types.ts

@@ -0,0 +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,
+};

package/src/utils.ts

@@ -0,0 +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;
+}