@tagma/sdk 0.7.3 → 0.7.5

package/src/schema.ts

@@ -1,379 +0,0 @@
-import yaml from 'js-yaml';
-import { relative } from 'path';
-import type {
-  PipelineConfig,
-  RawPipelineConfig,
-  RawTrackConfig,
-  RawTaskConfig,
-  TrackConfig,
-  TaskConfig,
-  Permissions,
-  CompletionConfig,
-} from './types';
-import { truncateForName, validatePath } from './utils';
-import { DEFAULT_PERMISSIONS } from './types';
-import { buildDag } from './dag';
-
-// ═══ YAML Parsing ═══
-
-export function parseYaml(content: string): RawPipelineConfig {
-  const doc = yaml.load(content) as { pipeline?: unknown };
-  if (!doc?.pipeline) {
-    throw new Error('YAML must contain a top-level "pipeline" key');
-  }
-  if (typeof doc.pipeline !== 'object' || Array.isArray(doc.pipeline)) {
-    throw new Error('pipeline must be an object');
-  }
-  const p = doc.pipeline as RawPipelineConfig;
-  if (!p.name) throw new Error('pipeline.name is required');
-  if (!Array.isArray(p.tracks)) throw new Error('pipeline.tracks must be an array');
-  if (p.tracks.length === 0) throw new Error('pipeline.tracks must be non-empty');
-
-  // D14: Detect duplicate track IDs before per-track validation so the error
-  // message is clear ("Duplicate track id") rather than a confusing DAG error
-  // ("Duplicate task ID: track.task_x") that only surfaces at runPipeline time.
-  const seenTrackIds = new Set<string>();
-  for (const track of p.tracks) {
-    if (track.id) {
-      if (seenTrackIds.has(track.id)) {
-        throw new Error(`Duplicate track id "${track.id}": each track must have a unique id.`);
-      }
-      seenTrackIds.add(track.id);
-    }
-  }
-
-  for (const track of p.tracks) {
-    validateRawTrack(track);
-  }
-  return p;
-}
-
-// D8: IDs must start with a letter or underscore and contain only
-// alphanumerics, underscores, and hyphens. Dots are 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 assertValidId(id: string, label: string): void {
-  if (!ID_RE.test(id)) {
-    throw new Error(
-      `${label}: id "${id}" is invalid. IDs must match /^[A-Za-z_][A-Za-z0-9_-]*$/ ` +
-        `(letters, digits, underscores, hyphens; no dots or spaces; must start with letter/underscore).`,
-    );
-  }
-}
-
-function validateRawTrack(track: RawTrackConfig): void {
-  if (!track || typeof track !== 'object' || Array.isArray(track)) {
-    throw new Error('track must be an object');
-  }
-  if (!track.id) throw new Error('track.id is required');
-  assertValidId(track.id, `track "${track.id}"`);
-  if (!track.name) throw new Error(`track "${track.id}": name is required`);
-  if (!Array.isArray(track.tasks)) {
-    throw new Error(`track "${track.id}": tasks must be an array`);
-  }
-  if (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 || typeof task !== 'object' || Array.isArray(task)) {
-    throw new Error(`track "${trackId}": task must be an object`);
-  }
-  if (!task.id) throw new Error(`track "${trackId}": task.id is required`);
-  assertValidId(task.id, `task "${task.id}" in track "${trackId}"`);
-
-  const hasPromptKey = typeof task.prompt === 'string';
-  const hasCommandKey = typeof task.command === 'string';
-  if (!hasPromptKey && !hasCommandKey) {
-    throw new Error(`task "${task.id}": must have either "prompt" or "command"`);
-  }
-  if (hasPromptKey && hasCommandKey) {
-    throw new Error(`task "${task.id}": cannot have both "prompt" and "command"`);
-  }
-  // Empty-content tasks (e.g. `prompt: ''`) are allowed at parse time and
-  // flagged as hard validation errors by validate-raw.ts.
-}
-
-// ═══ Config Inheritance Resolution ═══
-
-export function resolveConfig(raw: RawPipelineConfig, workDir: string): PipelineConfig {
-  // Build qualified ID set for resolving bare continue_from references
-  const allQualifiedIds = new Set<string>();
-  for (const t of raw.tracks) {
-    if (!t.id) continue;
-    for (const tk of t.tasks ?? []) {
-      if (tk.id) allQualifiedIds.add(`${t.id}.${tk.id}`);
-    }
-  }
-
-  function qualifyContinueFrom(ref: string, trackId: string): string {
-    // Already qualified
-    if (allQualifiedIds.has(ref)) return ref;
-    // Same-track shorthand
-    const sameTrack = `${trackId}.${ref}`;
-    if (allQualifiedIds.has(sameTrack)) return sameTrack;
-    // Cross-track bare lookup — must be unambiguous
-    let match: string | null = null;
-    for (const qid of allQualifiedIds) {
-      if (qid.endsWith(`.${ref}`)) {
-        if (match !== null) return ref; // ambiguous — leave as-is
-        match = qid;
-      }
-    }
-    return match ?? ref; // not found — leave as-is (validated elsewhere)
-  }
-
-  const tracks: TrackConfig[] = raw.tracks.map((rawTrack) => {
-    const trackDriver = rawTrack.driver ?? raw.driver;
-    // validatePath enforces no .. traversal and no absolute paths escaping workDir.
-    const trackCwd = rawTrack.cwd ? validatePath(rawTrack.cwd, workDir) : 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
-          ? qualifyContinueFrom(rawTask.continue_from, rawTrack.id)
-          : undefined,
-        // Inheritance: Task > Track > Pipeline
-        model: rawTask.model ?? rawTrack.model ?? raw.model,
-        reasoning_effort:
-          rawTask.reasoning_effort ?? rawTrack.reasoning_effort ?? raw.reasoning_effort,
-        permissions: rawTask.permissions ?? rawTrack.permissions ?? raw.permissions ?? DEFAULT_PERMISSIONS,
-        driver: rawTask.driver ?? trackDriver ?? 'opencode',
-        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 ? validatePath(rawTask.cwd, workDir) : trackCwd,
-        // Unified bindings have no inheritance; they describe
-        // per-task data flow, not cross-task defaults.
-        inputs: rawTask.inputs,
-        outputs: rawTask.outputs,
-      };
-    });
-
-    return {
-      id: rawTrack.id,
-      name: rawTrack.name,
-      color: rawTrack.color,
-      agent_profile: rawTrack.agent_profile,
-      model: rawTrack.model ?? raw.model,
-      reasoning_effort: rawTrack.reasoning_effort ?? raw.reasoning_effort,
-      permissions: rawTrack.permissions ?? raw.permissions ?? DEFAULT_PERMISSIONS,
-      driver: trackDriver ?? 'opencode',
-      cwd: trackCwd,
-      middlewares: rawTrack.middlewares,
-      on_failure: rawTrack.on_failure ?? 'skip_downstream',
-      tasks,
-    };
-  });
-
-  return {
-    name: raw.name,
-    driver: raw.driver,
-    model: raw.model,
-    reasoning_effort: raw.reasoning_effort,
-    permissions: raw.permissions,
-    timeout: raw.timeout,
-    plugins: raw.plugins,
-    hooks: raw.hooks,
-    tracks,
-  };
-}
-
-// Field-by-field permissions comparison — avoids relying on JSON.stringify key order.
-function permissionsEqual(a: Permissions | undefined, b: Permissions | undefined): boolean {
-  if (a === b) return true;
-  if (!a || !b) return false;
-  return a.read === b.read && a.write === b.write && a.execute === b.execute;
-}
-
-function isDefaultExitCodeCompletion(completion: CompletionConfig | undefined): boolean {
-  if (!completion || completion.type !== 'exit_code') return false;
-  const {
-    type: _type,
-    expect,
-    ...rest
-  } = completion as CompletionConfig & {
-    expect?: unknown;
-  };
-  if (Object.keys(rest).length > 0) return false;
-  return expect === undefined || expect === 0;
-}
-
-function stripDefaultTaskCompletion<T extends { completion?: CompletionConfig }>(task: T): T {
-  if (!isDefaultExitCodeCompletion(task.completion)) return task;
-  const { completion: _completion, ...rest } = task;
-  return rest as T;
-}
-
-// `continue_from` is a prompt-only field — it tells AI drivers with
-// session-resume capability to thread off an upstream prompt task's context.
-// A command task runs as a plain shell subprocess and has no session to
-// resume, so any `continue_from` on a command task is dead weight. Drop it
-// at serialization time so YAML on disk never carries the stale field after
-// a user toggles task mode from prompt → command. The tagma-yaml agent's
-// system prompt (apps/editor/server/opencode-seed.ts) documents this
-// stripping — keep them in sync.
-function stripPromptOnlyFieldsFromCommandTask<
-  T extends { command?: string; continue_from?: string },
->(task: T): T {
-  if (task.command === undefined || task.continue_from === undefined) return task;
-  const { continue_from: _cf, ...rest } = task;
-  return rest as T;
-}
-
-function stripForSerialization<T extends PipelineConfig | RawPipelineConfig>(
-  config: T,
-): T {
-  return {
-    ...config,
-    tracks: config.tracks.map((track) => ({
-      ...track,
-      tasks: track.tasks.map((task) =>
-        stripPromptOnlyFieldsFromCommandTask(stripDefaultTaskCompletion(task)),
-      ),
-    })),
-  } as T;
-}
-
-// ═══ YAML Serialization ═══
-
-/**
- * Serialize a pipeline config back to YAML string.
- * Wraps the config under the top-level `pipeline` key as expected by parseYaml.
- */
-export function serializePipeline(config: PipelineConfig | RawPipelineConfig): string {
-  return yaml.dump(
-    { pipeline: stripForSerialization(config) },
-    { lineWidth: 120, indent: 2 },
-  );
-}
-
-/**
- * Convert a resolved PipelineConfig back to a RawPipelineConfig for serialization.
- * Strips injected defaults and converts absolute cwd paths back to relative so the
- * resulting YAML is portable across machines.
- *
- * Use this when you need to save a config that was previously loaded via
- * loadPipeline(). For a pure load→edit→save cycle on raw YAML, prefer
- * parseYaml() → edit RawPipelineConfig → serializePipeline().
- */
-export function deresolvePipeline(config: PipelineConfig, workDir: string): RawPipelineConfig {
-  const tracks: RawTrackConfig[] = config.tracks.map((track) => {
-    const trackCwdRel =
-      track.cwd && track.cwd !== workDir ? relative(workDir, track.cwd) : undefined;
-    const effectiveTrackDriver = track.driver ?? config.driver ?? 'opencode';
-    const effectiveTrackModel = track.model ?? config.model;
-    const effectiveTrackReasoning = track.reasoning_effort ?? config.reasoning_effort;
-
-    const tasks: RawTaskConfig[] = track.tasks.map((task) => {
-      const taskCwdRel =
-        task.cwd && task.cwd !== track.cwd ? relative(workDir, task.cwd) : undefined;
-
-      return {
-        id: task.id,
-        ...(task.name ? { name: task.name } : {}),
-        ...(task.prompt !== undefined ? { prompt: task.prompt } : {}),
-        ...(task.command !== undefined ? { command: task.command } : {}),
-        ...(task.depends_on?.length ? { depends_on: task.depends_on } : {}),
-        ...(task.trigger ? { trigger: task.trigger } : {}),
-        ...(task.continue_from ? { continue_from: task.continue_from } : {}),
-        ...(taskCwdRel ? { cwd: taskCwdRel } : {}),
-        ...(task.model && task.model !== effectiveTrackModel ? { model: task.model } : {}),
-        ...(task.reasoning_effort && task.reasoning_effort !== effectiveTrackReasoning
-          ? { reasoning_effort: task.reasoning_effort }
-          : {}),
-        ...(task.driver && task.driver !== effectiveTrackDriver ? { driver: task.driver } : {}),
-        ...(task.timeout ? { timeout: task.timeout } : {}),
-        ...(task.middlewares !== undefined ? { middlewares: task.middlewares } : {}),
-        ...(task.completion && !isDefaultExitCodeCompletion(task.completion)
-          ? { completion: task.completion }
-          : {}),
-        ...(task.agent_profile ? { agent_profile: task.agent_profile } : {}),
-        ...(task.permissions && !permissionsEqual(task.permissions, track.permissions)
-          ? { permissions: task.permissions }
-          : {}),
-        ...(task.inputs && Object.keys(task.inputs).length > 0 ? { inputs: task.inputs } : {}),
-        ...(task.outputs && Object.keys(task.outputs).length > 0 ? { outputs: task.outputs } : {}),
-      };
-    });
-
-    return {
-      id: track.id,
-      name: track.name,
-      ...(track.color ? { color: track.color } : {}),
-      ...(track.agent_profile ? { agent_profile: track.agent_profile } : {}),
-      ...(track.model && track.model !== config.model ? { model: track.model } : {}),
-      ...(track.reasoning_effort && track.reasoning_effort !== config.reasoning_effort
-        ? { reasoning_effort: track.reasoning_effort }
-        : {}),
-      ...(track.driver && track.driver !== (config.driver ?? 'opencode')
-        ? { driver: track.driver }
-        : {}),
-      ...(trackCwdRel ? { cwd: trackCwdRel } : {}),
-      ...(track.middlewares?.length ? { middlewares: track.middlewares } : {}),
-      ...(track.on_failure && track.on_failure !== 'skip_downstream'
-        ? { on_failure: track.on_failure }
-        : {}),
-      ...(track.permissions && !permissionsEqual(track.permissions, config.permissions ?? DEFAULT_PERMISSIONS)
-        ? { permissions: track.permissions }
-        : {}),
-      tasks,
-    };
-  });
-
-  return {
-    name: config.name,
-    ...(config.driver ? { driver: config.driver } : {}),
-    ...(config.model ? { model: config.model } : {}),
-    ...(config.reasoning_effort ? { reasoning_effort: config.reasoning_effort } : {}),
-    ...(config.permissions && !permissionsEqual(config.permissions, DEFAULT_PERMISSIONS)
-      ? { permissions: config.permissions }
-      : {}),
-    ...(config.timeout ? { timeout: config.timeout } : {}),
-    ...(config.plugins?.length ? { plugins: config.plugins } : {}),
-    ...(config.hooks ? { hooks: config.hooks } : {}),
-    tracks,
-  };
-}
-
-// ═══ Offline Validation ═══
-
-/**
- * Validate a pipeline config without executing it.
- * Only checks structural/DAG correctness — does not check plugin registration.
- * Returns an array of error messages (empty = valid).
- */
-export function validateConfig(config: PipelineConfig): string[] {
-  const errors: string[] = [];
-  try {
-    buildDag(config);
-  } catch (err) {
-    errors.push(err instanceof Error ? err.message : String(err));
-  }
-  return errors;
-}
-
-// ═══ Full Parse Pipeline ═══
-
-export async function loadPipeline(yamlContent: string, workDir: string): Promise<PipelineConfig> {
-  const raw = parseYaml(yamlContent);
-  return resolveConfig(raw, workDir);
-}

package/src/tagma.test.ts

@@ -1,155 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { createTagma } from './tagma';
-import type { DriverPlugin, TagmaPlugin, TaskResult } from './types';
-import type { TagmaRuntime } from './runtime';
-
-function makeDir(prefix: string): string {
-  return mkdtempSync(join(tmpdir(), prefix));
-}
-
-function makeDriver(name: string, marker: string[]): DriverPlugin {
-  return {
-    name,
-    capabilities: { sessionResume: false, systemPrompt: false, outputFormat: false },
-    async buildCommand() {
-      marker.push(name);
-      return { args: ['echo', name] };
-    },
-  };
-}
-
-describe('createTagma', () => {
-  test('runs command tasks through the configured runtime', async () => {
-    const calls: string[] = [];
-    const taskResult: TaskResult = {
-      exitCode: 0,
-      stdout: 'runtime-ok',
-      stderr: '',
-      stdoutPath: null,
-      stderrPath: null,
-      stdoutBytes: 10,
-      stderrBytes: 0,
-      durationMs: 1,
-      sessionId: null,
-      normalizedOutput: null,
-      failureKind: null,
-    };
-    const runtime: TagmaRuntime = {
-      async runCommand(command, cwd) {
-        calls.push(`${cwd}:${command}`);
-        return taskResult;
-      },
-      async runSpawn() {
-        throw new Error('runSpawn should not be called for command tasks');
-      },
-    };
-    const tagma = createTagma({ builtins: false, runtime });
-    const dir = makeDir('tagma-runtime-run-');
-    try {
-      const result = await tagma.run(
-        {
-          name: 'runtime-run',
-          tracks: [
-            {
-              id: 't',
-              name: 'T',
-              tasks: [{ id: 'cmd', name: 'cmd', command: 'fake-only-command' }],
-            },
-          ],
-        },
-        {
-          cwd: dir,
-          skipPluginLoading: true,
-        },
-      );
-
-      expect(result.success).toBe(true);
-      expect(calls).toEqual([`${dir}:fake-only-command`]);
-      expect(result.states.get('t.cmd')?.result?.stdout).toBe('runtime-ok');
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  test('registers capability plugins passed to options', () => {
-    const seen: string[] = [];
-    const driver = makeDriver('driver-plugin', seen);
-    const plugin: TagmaPlugin = {
-      name: 'tagma-plugin-local',
-      capabilities: {
-        drivers: {
-          mock: driver,
-        },
-      },
-    };
-
-    const tagma = createTagma({ builtins: false, plugins: [plugin] });
-
-    expect(tagma.registry.getHandler<DriverPlugin>('drivers', 'mock')).toBe(driver);
-    expect(seen).toEqual([]);
-  });
-
-  test('instances own isolated plugin registries', () => {
-    const seenA: string[] = [];
-    const seenB: string[] = [];
-    const tagmaA = createTagma({ builtins: false });
-    const tagmaB = createTagma({ builtins: false });
-
-    tagmaA.registry.registerPlugin('drivers', 'mock', makeDriver('driver-a', seenA));
-    tagmaB.registry.registerPlugin('drivers', 'mock', makeDriver('driver-b', seenB));
-
-    expect(tagmaA.registry.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('driver-a');
-    expect(tagmaB.registry.getHandler<DriverPlugin>('drivers', 'mock').name).toBe('driver-b');
-    expect(seenA).toEqual([]);
-    expect(seenB).toEqual([]);
-  });
-
-  test('run uses only the instance registry', async () => {
-    const tagma = createTagma({ builtins: false });
-    const dir = makeDir('tagma-instance-run-');
-    try {
-      await expect(
-        tagma.run(
-          {
-            name: 'instance-run',
-            tracks: [
-              {
-                id: 't',
-                name: 'T',
-                tasks: [{ id: 'prompt', name: 'prompt', prompt: 'hello' }],
-              },
-            ],
-          },
-          {
-            cwd: dir,
-            skipPluginLoading: true,
-          },
-        ),
-      ).rejects.toThrow(/driver "opencode" not registered/);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  test('validate returns structural pipeline errors without running tasks', () => {
-    const tagma = createTagma({ builtins: false });
-
-    expect(
-      tagma.validate({
-        name: 'invalid',
-        tracks: [
-          {
-            id: 't',
-            name: 'T',
-            tasks: [
-              { id: 'a', name: 'A', command: 'echo a', depends_on: ['missing'] },
-            ],
-          },
-        ],
-      }),
-    ).toEqual(['Task reference "missing" not found']);
-  });
-});

package/src/tagma.ts

@@ -1,62 +0,0 @@
-import { runPipeline, type EngineResult, type RunPipelineOptions } from './engine';
-import { bootstrapBuiltins } from './bootstrap';
-import { PluginRegistry } from './registry';
-import { validateConfig } from './schema';
-import { bunRuntime, type TagmaRuntime } from './runtime';
-import type { PipelineConfig, TagmaPlugin } from './types';
-
-export interface CreateTagmaOptions {
-  /**
-   * Registry used by this SDK instance. Omit to create an isolated registry.
-   */
-  readonly registry?: PluginRegistry;
-  /**
-   * Register built-in drivers/triggers/completions/middlewares into the
-   * instance registry. Defaults to true.
-   */
-  readonly builtins?: boolean;
-  /**
-   * Package-level capability plugins to register into this SDK instance.
-   */
-  readonly plugins?: readonly TagmaPlugin[];
-  /**
-   * Runtime implementation used for command and driver process execution.
-   * Defaults to the SDK's Bun runtime.
-   */
-  readonly runtime?: TagmaRuntime;
-}
-
-export interface TagmaRunOptions extends Omit<RunPipelineOptions, 'registry'> {
-  readonly cwd: string;
-}
-
-export interface Tagma {
-  readonly registry: PluginRegistry;
-  run(config: PipelineConfig, options: TagmaRunOptions): Promise<EngineResult>;
-  validate(config: PipelineConfig): readonly string[];
-}
-
-export function createTagma(options: CreateTagmaOptions = {}): Tagma {
-  const registry = options.registry ?? new PluginRegistry();
-  const runtime = options.runtime ?? bunRuntime();
-  if (options.builtins !== false) {
-    bootstrapBuiltins(registry);
-  }
-  for (const plugin of options.plugins ?? []) {
-    registry.registerTagmaPlugin(plugin);
-  }
-
-  return {
-    registry,
-    run(config, { cwd, ...runOptions }) {
-      return runPipeline(config, cwd, {
-        ...runOptions,
-        registry,
-        runtime,
-      });
-    },
-    validate(config) {
-      return validateConfig(config);
-    },
-  };
-}