@tagma/sdk 0.7.4 → 0.7.6

package/src/triggers/file.ts

@@ -1,131 +0,0 @@
-import { resolve, dirname } from 'path';
-import type { TriggerPlugin, TriggerContext } from '../types';
-import { parseDuration, validatePath } from '../utils';
-import { TriggerTimeoutError } from '../core/trigger-errors';
-
-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 waitForFile({ filePath, safePath, timeoutMs, timeoutLabel: config.timeout, ctx });
-  },
-};
-
-async function waitForFile(options: {
-  readonly filePath: string;
-  readonly safePath: string;
-  readonly timeoutMs: number;
-  readonly timeoutLabel: unknown;
-  readonly ctx: TriggerContext;
-}): Promise<unknown> {
-  const { filePath, safePath, timeoutMs, timeoutLabel, ctx } = options;
-  if (ctx.signal.aborted) throw new Error('Pipeline aborted');
-
-  const dir = dirname(safePath);
-  await ctx.runtime.ensureDir(dir).catch(() => {
-    /* best effort; runtime watch will surface real failures */
-  });
-
-  const watchController = new AbortController();
-  let removeAbortListener = () => {
-    /* no-op until the abort listener is installed */
-  };
-  const abortPromise = new Promise<never>((_, reject) => {
-    const onAbort = () => {
-      watchController.abort();
-      reject(new Error('Pipeline aborted'));
-    };
-    ctx.signal.addEventListener('abort', onAbort, { once: true });
-    removeAbortListener = () => ctx.signal.removeEventListener('abort', onAbort);
-  });
-
-  let timer: ReturnType<typeof setTimeout> | null = null;
-  const timeoutPromise =
-    timeoutMs > 0
-      ? new Promise<never>((_, reject) => {
-          timer = setTimeout(() => {
-            watchController.abort();
-            reject(
-              new TriggerTimeoutError(
-                `file trigger timeout: ${filePath} did not appear within ${timeoutLabel}`,
-              ),
-            );
-          }, timeoutMs);
-        })
-      : new Promise<never>(() => {
-          /* no timeout */
-        });
-
-  async function watchLoop(): Promise<unknown> {
-    // Pass `cwd: dir` so runtimes can emit paths relative to the watched
-    // directory. The 'add'/'change' events are resolved against `dir` before
-    // comparison, preserving the old chokidar behavior without coupling this
-    // trigger to chokidar or Bun file APIs.
-    for await (const event of ctx.runtime.watch(dir, {
-      ignoreInitial: true,
-      depth: 0,
-      cwd: dir,
-      awaitWriteFinishMs: 100,
-      signal: watchController.signal,
-    })) {
-      if (event.type === 'ready') {
-        let exists = false;
-        try {
-          exists = await ctx.runtime.fileExists(safePath);
-        } catch (err) {
-          throw new Error(
-            `file trigger existence check failed: ${err instanceof Error ? err.message : String(err)}`,
-          );
-        }
-        if (exists) return { path: safePath };
-        continue;
-      }
-
-      if (
-        (event.type === 'add' || event.type === 'change') &&
-        pathsEqual(resolve(dir, event.path), safePath)
-      ) {
-        return { path: safePath };
-      }
-    }
-
-    if (ctx.signal.aborted) throw new Error('Pipeline aborted');
-    throw new Error(`file trigger watch ended before ${filePath} appeared`);
-  }
-
-  try {
-    return await Promise.race([watchLoop(), timeoutPromise, abortPromise]);
-  } finally {
-    if (timer !== null) clearTimeout(timer);
-    removeAbortListener();
-    watchController.abort();
-  }
-}

package/src/triggers/manual.ts

@@ -1,86 +0,0 @@
-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 +0,0 @@
-// ═══ 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-api.ts

@@ -1,8 +0,0 @@
-export {
-  parseDuration,
-  validatePath,
-  generateRunId,
-  nowISO,
-  truncateForName,
-} from './utils';
-

package/src/utils.test.ts

@@ -1,28 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { validatePath } from './utils';
-
-describe('validatePath', () => {
-  test('rejects real parent traversal outside the project root', () => {
-    const root = mkdtempSync(join(tmpdir(), 'tagma-validate-path-'));
-    try {
-      expect(() => validatePath('../outside', root)).toThrow(/escapes project root/);
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-
-  test('allows project-local names that merely start with two dots', () => {
-    const root = mkdtempSync(join(tmpdir(), 'tagma-validate-path-'));
-    try {
-      const inside = join(root, '..inside');
-      mkdirSync(inside);
-
-      expect(validatePath('..inside', root)).toBe(inside);
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-});

package/src/utils.ts

@@ -1,203 +0,0 @@
-import { isAbsolute, resolve, relative, parse as parsePath, sep } from 'path';
-import { realpathSync, lstatSync, existsSync } from 'fs';
-import { randomBytes } from 'crypto';
-
-const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
-
-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|d)`);
-  }
-  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;
-    case 'd':
-      return value * 86_400_000;
-    default:
-      throw new Error(`Unknown duration unit: "${unit}"`);
-  }
-}
-
-export function validatePath(filePath: string, projectRoot: string): string {
-  const resolved = resolve(projectRoot, filePath);
-
-  // 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 === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
-    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 === '..' || realRel.startsWith(`..${sep}`) || isAbsolute(realRel)) {
-      throw new Error(
-        `Security: path "${filePath}" resolves via symlink to "${real}" which escapes project root "${realRoot}".`,
-      );
-    }
-  }
-
-  return resolved;
-}
-
-export function generateRunId(): string {
-  const ts = Date.now().toString(36);
-  const rand = randomBytes(6).toString('hex');
-  return `run_${ts}_${rand}`;
-}
-
-export function truncateForName(text: string, maxLen = 40): string {
-  const first = text.split('\n')[0]!.trim();
-  // Guard: if the first line is empty (e.g. prompt is all whitespace/newlines),
-  // fall back to the raw text trimmed rather than silently producing an empty name.
-  if (!first) return text.trim().slice(0, maxLen) || '...';
-  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;
-  if (IS_WINDOWS) {
-    // On Windows (cmd.exe), double-quote and escape embedded quotes + backslashes
-    return '"' + arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
-  }
-  // On Unix, use single quotes to prevent $variable expansion.
-  // Escape embedded single quotes via the '\'' idiom.
-  return "'" + arg.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;
-}

package/src/validate-raw-plugin-types.test.ts

@@ -1,60 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { compileYamlContent } from './yaml-compiler';
-import { validateRaw } from './validate-raw';
-import type { RawPipelineConfig } from './types';
-
-describe('validateRaw known plugin types', () => {
-  test('warns when pipeline, track, or prompt task references an unknown driver', () => {
-    const config: RawPipelineConfig = {
-      name: 'driver checks',
-      driver: 'missing-pipeline',
-      tracks: [
-        {
-          id: 'main',
-          name: 'Main',
-          driver: 'missing-track',
-          tasks: [
-            {
-              id: 'prompt',
-              name: 'Prompt',
-              prompt: 'hello',
-              driver: 'missing-task',
-            },
-          ],
-        },
-      ],
-    };
-
-    const diagnostics = validateRaw(config, { drivers: ['opencode'] });
-    expect(diagnostics.map((d) => d.message)).toEqual(
-      expect.arrayContaining([
-        'Unknown driver type "missing-pipeline"',
-        'Unknown driver type "missing-track"',
-        'Unknown driver type "missing-task"',
-      ]),
-    );
-  });
-
-  test('compileYamlContent includes unknown driver warnings from knownTypes.drivers', () => {
-    const result = compileYamlContent(
-      [
-        'pipeline:',
-        '  name: Unknown Driver',
-        '  driver: ghost',
-        '  tracks:',
-        '    - id: main',
-        '      name: Main',
-        '      tasks:',
-        '        - id: prompt',
-        '          name: Prompt',
-        '          prompt: Hello',
-        '',
-      ].join('\n'),
-      { knownTypes: { drivers: ['opencode'] } },
-    );
-
-    expect(result.validation.warnings.map((w) => w.message)).toContain(
-      'Unknown driver type "ghost"',
-    );
-  });
-});

package/src/validate-raw-ports.test.ts

@@ -1,136 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import type { RawPipelineConfig, RawTaskConfig } from './types';
-import { validateRaw } from './validate-raw';
-
-function commandTask(overrides: Partial<RawTaskConfig> & { id: string }): RawTaskConfig {
-  return { command: 'echo {{inputs.city}}', ...overrides };
-}
-
-function promptTask(overrides: Partial<RawTaskConfig> & { id: string }): RawTaskConfig {
-  return { prompt: 'hello {{inputs.city}}', ...overrides };
-}
-
-function config(tasks: RawTaskConfig[]): RawPipelineConfig {
-  return {
-    name: 'p',
-    tracks: [{ id: 't', name: 'T', tasks }],
-  };
-}
-
-function errorsFor(task: RawTaskConfig) {
-  return validateRaw(config([task]));
-}
-
-describe('validateRaw — ports migration', () => {
-  test('rejects ports with a migration message', () => {
-    const errors = errorsFor(
-      commandTask({
-        id: 'a',
-        ports: { inputs: [{ name: 'city', type: 'string' }] },
-      }),
-    );
-    expect(errors.some((e) => e.path === 'tracks[0].tasks[0].ports')).toBe(true);
-    expect(errors.some((e) => /replaced by typed inputs\/outputs/.test(e.message))).toBe(true);
-  });
-
-  test('empty ports is still rejected', () => {
-    const errors = errorsFor(commandTask({ id: 'a', ports: {} }));
-    expect(errors.some((e) => /ports has been replaced/.test(e.message))).toBe(true);
-  });
-});
-
-describe('validateRaw — unified typed bindings', () => {
-  test('accepts typed command inputs and outputs', () => {
-    const errors = errorsFor(
-      commandTask({
-        id: 'a',
-        inputs: { city: { type: 'string', required: true } },
-        outputs: { temp: { type: 'number' } },
-      }),
-    );
-    expect(errors).toEqual([]);
-  });
-
-  test('rejects invalid binding maps, names, type, and enum shape', () => {
-    const errors = errorsFor(
-      commandTask({
-        id: 'a',
-        command: 'echo {{inputs.city}}',
-        inputs: {
-          'bad-name': { value: 'x' },
-          city: { type: 'made-up' as never },
-          kind: { type: 'enum' },
-        },
-        outputs: { ok: 'bad' as never },
-      }),
-    );
-    const msgs = errors.map((e) => e.message);
-    expect(msgs.some((m) => /binding name "bad-name" is invalid/.test(m))).toBe(true);
-    expect(msgs.some((m) => /task\.inputs\.city\.type must be one of/.test(m))).toBe(true);
-    expect(msgs.some((m) => /task\.inputs\.kind\.enum must be a non-empty/.test(m))).toBe(true);
-    expect(msgs.some((m) => /task\.outputs\.ok must be an object/.test(m))).toBe(true);
-  });
-
-  test('command placeholders must reference task.inputs', () => {
-    const errors = errorsFor(commandTask({ id: 'a', command: 'echo {{inputs.missing}}' }));
-    expect(errors.some((e) => e.message.includes('references "{{inputs.missing}}"'))).toBe(true);
-  });
-
-  test('fully-qualified input sources must reference direct dependencies', () => {
-    const errors = validateRaw(
-      config([
-        commandTask({ id: 'up', command: 'echo ok', outputs: { city: {} } }),
-        commandTask({
-          id: 'down',
-          command: 'echo {{inputs.city}}',
-          inputs: { city: { from: 't.up.outputs.city' } },
-        }),
-      ]),
-    );
-    expect(errors.some((e) => /not a direct dependency/.test(e.message))).toBe(true);
-  });
-});
-
-describe('validateRaw — prompt inferred bindings', () => {
-  test('prompt placeholders can reference direct upstream command outputs', () => {
-    const errors = validateRaw(
-      config([
-        commandTask({ id: 'up', command: 'echo ok', outputs: { city: { type: 'string' } } }),
-        promptTask({ id: 'p', depends_on: ['up'], prompt: 'city={{inputs.city}}' }),
-      ]),
-    );
-    expect(errors.some((e) => e.message.includes('references "{{inputs.city}}"'))).toBe(false);
-  });
-
-  test('two upstream command outputs with the same name are ambiguous for prompts', () => {
-    const errors = validateRaw(
-      config([
-        commandTask({ id: 'a', command: 'echo ok', outputs: { city: { type: 'string' } } }),
-        commandTask({ id: 'b', command: 'echo ok', outputs: { city: { type: 'string' } } }),
-        promptTask({ id: 'p', depends_on: ['a', 'b'], prompt: 'city={{inputs.city}}' }),
-      ]),
-    );
-    expect(errors.some((e) => /cannot disambiguate/.test(e.message))).toBe(true);
-  });
-
-  test('downstream commands with incompatible typed inputs conflict for prompt outputs', () => {
-    const errors = validateRaw(
-      config([
-        promptTask({ id: 'p', prompt: 'make date' }),
-        commandTask({
-          id: 'a',
-          depends_on: ['p'],
-          command: 'echo {{inputs.date}}',
-          inputs: { date: { type: 'string' } },
-        }),
-        commandTask({
-          id: 'b',
-          depends_on: ['p'],
-          command: 'echo {{inputs.date}}',
-          inputs: { date: { type: 'number' } },
-        }),
-      ]),
-    );
-    expect(errors.some((e) => /disagree on the shape of inferred output "date"/.test(e.message))).toBe(true);
-  });
-});