@tagma/sdk 0.6.12 → 0.7.1

package/src/schema-ports.test.ts

@@ -1,19 +1,12 @@
 import { describe, expect, test } from 'bun:test';
 import yaml from 'js-yaml';
 import type { PipelineConfig, RawPipelineConfig } from './types';
-import {
-  deresolvePipeline,
-  parseYaml,
-  resolveConfig,
-  serializePipeline,
-} from './schema';
+import { deresolvePipeline, parseYaml, resolveConfig, serializePipeline } from './schema';
 
 const WORK_DIR = process.platform === 'win32' ? 'D:\\fake-work' : '/fake-work';
 
-// ─── resolveConfig preserves ports ───────────────────────────────────
-
-describe('resolveConfig — ports passthrough', () => {
-  test('raw lightweight bindings survive onto the resolved task', () => {
+describe('schema — unified bindings passthrough', () => {
+  test('typed inputs and outputs survive onto the resolved task', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -24,94 +17,19 @@ describe('resolveConfig — ports passthrough', () => {
             {
               id: 'a',
               command: 'echo "{{inputs.city}}"',
-              inputs: {
-                city: { from: 't.plan.outputs.city', required: true },
-              },
-              outputs: {
-                report: { from: 'json.reportPath' },
-              },
+              inputs: { city: { from: 't.plan.outputs.city', type: 'string', required: true } },
+              outputs: { report: { from: 'json.reportPath', type: 'string' } },
             },
           ],
         },
       ],
     };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const task = resolved.tracks[0]!.tasks[0]!;
+    const task = resolveConfig(raw, WORK_DIR).tracks[0]!.tasks[0]!;
     expect(task.inputs).toEqual(raw.tracks[0]!.tasks[0]!.inputs!);
     expect(task.outputs).toEqual(raw.tracks[0]!.tasks[0]!.outputs!);
   });
 
-  test('raw ports survive onto the resolved task', () => {
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          tasks: [
-            {
-              id: 'a',
-              prompt: 'do it',
-              ports: {
-                inputs: [{ name: 'city', type: 'string', required: true }],
-                outputs: [{ name: 'temp', type: 'number', description: 'Celsius' }],
-              },
-            },
-          ],
-        },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const task = resolved.tracks[0]!.tasks[0]!;
-    expect(task.ports).toBeDefined();
-    expect(task.ports!.inputs).toEqual([
-      { name: 'city', type: 'string', required: true },
-    ]);
-    expect(task.ports!.outputs).toEqual([
-      { name: 'temp', type: 'number', description: 'Celsius' },
-    ]);
-  });
-
-  test('tasks without ports still resolve with ports === undefined', () => {
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        { id: 't', name: 'T', tasks: [{ id: 'a', prompt: 'do it' }] },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    expect(resolved.tracks[0]!.tasks[0]!.ports).toBeUndefined();
-  });
-
-  test('ports is not inherited from track or pipeline', () => {
-    // Ports describe a per-task I/O contract. If we accidentally pulled
-    // them from track defaults, two tasks in the same track would share
-    // input ports and downstream data-flow would be ambiguous. Test that
-    // a track with an unrelated `middlewares` default doesn't spread
-    // anywhere unexpected — purely a regression guard for the no-inherit
-    // invariant.
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          middlewares: [{ type: 'static_context', file: './x' }],
-          tasks: [{ id: 'a', prompt: 'x' }, { id: 'b', prompt: 'y' }],
-        },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    for (const task of resolved.tracks[0]!.tasks) {
-      expect(task.ports).toBeUndefined();
-    }
-  });
-});
-
-// ─── deresolvePipeline preserves ports ───────────────────────────────
-
-describe('deresolvePipeline — ports round-trip', () => {
-  test('lightweight bindings round-trip', () => {
+  test('typed inputs and outputs round-trip through deresolve', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -123,103 +41,49 @@ describe('deresolvePipeline — ports round-trip', () => {
               id: 'a',
               command: 'echo "{{inputs.city}}"',
               inputs: {
-                city: { from: 't.plan.outputs.city', required: true },
-                mode: { default: 'quick' },
-              },
-              outputs: {
-                raw: { from: 'stdout' },
+                city: {
+                  from: 't.plan.outputs.city',
+                  type: 'enum',
+                  enum: ['Shanghai', 'Paris'],
+                  required: true,
+                },
               },
+              outputs: { raw: { from: 'stdout' } },
             },
           ],
         },
       ],
     };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const back = deresolvePipeline(resolved, WORK_DIR);
+    const back = deresolvePipeline(resolveConfig(raw, WORK_DIR), WORK_DIR);
     expect(back.tracks[0]!.tasks[0]!.inputs).toEqual(raw.tracks[0]!.tasks[0]!.inputs!);
     expect(back.tracks[0]!.tasks[0]!.outputs).toEqual(raw.tracks[0]!.tasks[0]!.outputs!);
   });
 
-  test('ports with both inputs and outputs round-trip', () => {
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          tasks: [
-            {
-              id: 'a',
-              prompt: 'hi',
-              ports: {
-                inputs: [{ name: 'city', type: 'string', required: true }],
-                outputs: [{ name: 'temp', type: 'number' }],
-              },
-            },
-          ],
-        },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const back = deresolvePipeline(resolved, WORK_DIR);
-    expect(back.tracks[0]!.tasks[0]!.ports).toEqual(raw.tracks[0]!.tasks[0]!.ports!);
-  });
-
-  test('ports with only outputs round-trip', () => {
-    const raw: RawPipelineConfig = {
-      name: 'p',
-      tracks: [
-        {
-          id: 't',
-          name: 'T',
-          tasks: [
-            {
-              id: 'a',
-              command: 'echo hi',
-              ports: { outputs: [{ name: 'x', type: 'string' }] },
-            },
-          ],
-        },
-      ],
-    };
-    const resolved = resolveConfig(raw, WORK_DIR);
-    const back = deresolvePipeline(resolved, WORK_DIR);
-    expect(back.tracks[0]!.tasks[0]!.ports).toEqual({
-      outputs: [{ name: 'x', type: 'string' }],
-    });
-  });
-
-  test('empty ports ({}) is dropped on deresolve', () => {
-    // YAML round-trip prefers field absence over `ports: {}` so a task
-    // that once declared a port but had it cleared in the editor
-    // doesn't persist a useless empty object in the file.
+  test('empty binding maps are dropped on deresolve', () => {
     const resolved: PipelineConfig = {
       name: 'p',
       tracks: [
         {
           id: 't',
           name: 'T',
-          driver: 'opencode',
-          permissions: { read: true, write: false, execute: false },
-          on_failure: 'skip_downstream',
           tasks: [
             {
               id: 'a',
               name: 'a',
               prompt: 'hi',
-              permissions: { read: true, write: false, execute: false },
-              driver: 'opencode',
-              ports: {},
+              inputs: {},
+              outputs: {},
             },
           ],
         },
       ],
     };
     const back = deresolvePipeline(resolved, WORK_DIR);
-    expect(back.tracks[0]!.tasks[0]!.ports).toBeUndefined();
+    expect(back.tracks[0]!.tasks[0]!.inputs).toBeUndefined();
+    expect(back.tracks[0]!.tasks[0]!.outputs).toBeUndefined();
   });
 
-  test('YAML round-trip via serializePipeline preserves the full ports shape', () => {
+  test('YAML round-trip preserves typed unified binding shape', () => {
     const raw: RawPipelineConfig = {
       name: 'p',
       tracks: [
@@ -230,18 +94,13 @@ describe('deresolvePipeline — ports round-trip', () => {
             {
               id: 'classify',
               prompt: 'pick a bucket',
-              ports: {
-                inputs: [
-                  { name: 'doc', type: 'string', required: true, description: 'Full text' },
-                ],
-                outputs: [
-                  {
-                    name: 'bucket',
-                    type: 'enum',
-                    enum: ['spam', 'ham'],
-                    description: 'Classification',
-                  },
-                ],
+              inputs: { doc: { type: 'string', required: true, description: 'Full text' } },
+              outputs: {
+                bucket: {
+                  type: 'enum',
+                  enum: ['spam', 'ham'],
+                  description: 'Classification',
+                },
               },
             },
           ],
@@ -250,14 +109,11 @@ describe('deresolvePipeline — ports round-trip', () => {
     };
     const yamlText = serializePipeline(raw);
     const parsed = (yaml.load(yamlText) as { pipeline: RawPipelineConfig }).pipeline;
-    expect(parsed.tracks[0]!.tasks[0]!.ports).toEqual(raw.tracks[0]!.tasks[0]!.ports!);
+    expect(parsed.tracks[0]!.tasks[0]!.inputs).toEqual(raw.tracks[0]!.tasks[0]!.inputs!);
+    expect(parsed.tracks[0]!.tasks[0]!.outputs).toEqual(raw.tracks[0]!.tasks[0]!.outputs!);
   });
-});
-
-// ─── parseYaml accepts ports ─────────────────────────────────────────
 
-describe('parseYaml — accepts ports declarations', () => {
-  test('real-world YAML with lightweight bindings parses cleanly', () => {
+  test('real-world YAML with typed bindings parses cleanly', () => {
     const text = `pipeline:
   name: demo
   tracks:
@@ -267,56 +123,27 @@ describe('parseYaml — accepts ports declarations', () => {
         - id: build
           command: bun run build
           outputs:
-            bundlePath: { from: json.bundlePath }
+            bundlePath:
+              from: json.bundlePath
+              type: string
         - id: test
           depends_on: [build]
           command: 'bun test "{{inputs.bundlePath}}"'
           inputs:
             bundlePath:
               from: t.build.outputs.bundlePath
+              type: string
               required: true
 `;
     const config = parseYaml(text);
-    const build = config.tracks[0]!.tasks[0]!;
-    const testTask = config.tracks[0]!.tasks[1]!;
-    expect(build.outputs!.bundlePath).toEqual({ from: 'json.bundlePath' });
-    expect(testTask.inputs!.bundlePath).toEqual({
+    expect(config.tracks[0]!.tasks[0]!.outputs!.bundlePath).toEqual({
+      from: 'json.bundlePath',
+      type: 'string',
+    });
+    expect(config.tracks[0]!.tasks[1]!.inputs!.bundlePath).toEqual({
       from: 't.build.outputs.bundlePath',
+      type: 'string',
       required: true,
     });
   });
-
-  test('real-world YAML with ports parses cleanly', () => {
-    const text = `pipeline:
-  name: demo
-  tracks:
-    - id: t
-      name: Main
-      tasks:
-        - id: plan
-          prompt: Pick a city and id
-          ports:
-            outputs:
-              - name: city
-                type: string
-                description: Target city
-              - name: id
-                type: number
-        - id: fetch
-          depends_on: [plan]
-          command: 'weather.sh --city "{{inputs.city}}" --id {{inputs.id}}'
-          ports:
-            inputs:
-              - { name: city, type: string, required: true }
-              - { name: id, type: number, required: true }
-            outputs:
-              - { name: temp, type: number }
-`;
-    const config = parseYaml(text);
-    const plan = config.tracks[0]!.tasks[0]!;
-    const fetch = config.tracks[0]!.tasks[1]!;
-    expect(plan.ports!.outputs!.map((p) => p.name)).toEqual(['city', 'id']);
-    expect(fetch.ports!.inputs!.map((p) => p.name)).toEqual(['city', 'id']);
-    expect(fetch.ports!.outputs!.map((p) => p.name)).toEqual(['temp']);
-  });
 });

package/src/tagma.test.ts

@@ -0,0 +1,84 @@
+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, PipelineConfig } from './types';
+
+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('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

@@ -0,0 +1,47 @@
+import { runPipeline, type EngineResult, type RunPipelineOptions } from './engine';
+import { bootstrapBuiltins } from './bootstrap';
+import { PluginRegistry } from './registry';
+import { validateConfig } from './schema';
+import type { PipelineConfig } 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;
+}
+
+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();
+  if (options.builtins !== false) {
+    bootstrapBuiltins(registry);
+  }
+
+  return {
+    registry,
+    run(config, { cwd, ...runOptions }) {
+      return runPipeline(config, cwd, {
+        ...runOptions,
+        registry,
+      });
+    },
+    validate(config) {
+      return validateConfig(config);
+    },
+  };
+}

package/src/utils-api.ts

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