@tagma/sdk 0.6.3 → 0.6.5

package/src/schema-ports.test.ts

@@ -0,0 +1,236 @@
+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';
+
+const WORK_DIR = process.platform === 'win32' ? 'D:\\fake-work' : '/fake-work';
+
+// ─── resolveConfig preserves ports ───────────────────────────────────
+
+describe('resolveConfig — ports passthrough', () => {
+  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('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.
+    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: {},
+            },
+          ],
+        },
+      ],
+    };
+    const back = deresolvePipeline(resolved, WORK_DIR);
+    expect(back.tracks[0]!.tasks[0]!.ports).toBeUndefined();
+  });
+
+  test('YAML round-trip via serializePipeline preserves the full ports shape', () => {
+    const raw: RawPipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              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',
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+    };
+    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!);
+  });
+});
+
+// ─── parseYaml accepts ports ─────────────────────────────────────────
+
+describe('parseYaml — accepts ports declarations', () => {
+  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/schema.ts

@@ -148,6 +148,9 @@ export function resolveConfig(raw: RawPipelineConfig, workDir: string): Pipeline
         completion: rawTask.completion,
         agent_profile: rawTask.agent_profile ?? rawTrack.agent_profile,
         cwd: rawTask.cwd ? validatePath(rawTask.cwd, workDir) : trackCwd,
+        // Ports: no inheritance — they describe per-task I/O contract, not
+        // cross-task defaults. Passed through as-is (including `undefined`).
+        ports: rawTask.ports,
       };
     });
 
@@ -274,6 +277,11 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
         ...(task.permissions && !permissionsEqual(task.permissions, track.permissions)
           ? { permissions: task.permissions }
           : {}),
+        ...(task.ports &&
+        ((task.ports.inputs && task.ports.inputs.length > 0) ||
+          (task.ports.outputs && task.ports.outputs.length > 0))
+          ? { ports: task.ports }
+          : {}),
       };
     });
 

package/src/sdk.ts

@@ -114,7 +114,21 @@ export {
   promptDocumentFromString,
   serializePromptDocument,
   appendContext,
+  prependContext,
+  renderInputsBlock,
+  renderOutputSchemaBlock,
 } from './prompt-doc';
 
+// ── Task ports (editor: substitute placeholders, resolve upstream
+//    values, extract downstream outputs; drivers that wrap the prompt
+//    may want substituteInputs on their own envelope) ──
+export {
+  substituteInputs,
+  extractInputReferences,
+  resolveTaskInputs,
+  extractTaskOutputs,
+} from './ports';
+export type { SubstituteResult, InputResolution, ExtractResult } from './ports';
+
 // ── All types from @tagma/types + runtime constants ──
 export * from './types';

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

@@ -0,0 +1,198 @@
+import { describe, expect, test } from 'bun:test';
+import { validateRaw } from './validate-raw';
+import type { RawPipelineConfig, RawTaskConfig, RawTrackConfig, TaskPorts } from './types';
+
+function task(overrides: Partial<RawTaskConfig> & { id: string }): RawTaskConfig {
+  return { prompt: 'do a thing', ...overrides };
+}
+
+function pipeline(tasks: RawTaskConfig[]): RawPipelineConfig {
+  const track: RawTrackConfig = { id: 't', name: 't', tasks };
+  return { name: 'test', tracks: [track] };
+}
+
+function errorsFor(taskConfig: RawTaskConfig): ReturnType<typeof validateRaw> {
+  return validateRaw(pipeline([taskConfig]));
+}
+
+/**
+ * Return only the errors whose path points inside the given task's
+ * `.ports` subtree, so assertions don't pick up unrelated cycle or
+ * name-validation errors that the rest of validate-raw emits.
+ */
+function portsErrors(errors: ReturnType<typeof validateRaw>): typeof errors {
+  return errors.filter(
+    (e) => e.path.includes('.ports.') || e.path.includes('.ports[') || /\.ports$/.test(e.path),
+  );
+}
+
+// ─── Structural validation ───────────────────────────────────────────
+
+describe('validateRaw — port structure', () => {
+  test('empty ports object is accepted (no-op)', () => {
+    const errors = errorsFor(task({ id: 'a', ports: {} }));
+    expect(portsErrors(errors)).toEqual([]);
+  });
+
+  test('rejects non-array ports.inputs', () => {
+    const ports = { inputs: 'not-an-array' as unknown as [] } as TaskPorts;
+    const errors = errorsFor(task({ id: 'a', ports }));
+    const e = portsErrors(errors);
+    expect(e.length).toBeGreaterThan(0);
+    expect(e[0]!.message).toMatch(/must be an array/);
+  });
+
+  test('rejects non-object port entry', () => {
+    const ports = { inputs: ['not-an-object' as unknown as never] } as TaskPorts;
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /must be an object/.test(e.message))).toBe(true);
+  });
+
+  test('requires port.name to be a non-empty string', () => {
+    const ports: TaskPorts = { inputs: [{ name: '', type: 'string' }] };
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /port\.name is required/.test(e.message))).toBe(true);
+  });
+
+  test('rejects invalid port name characters', () => {
+    const ports: TaskPorts = {
+      inputs: [
+        { name: 'has-hyphen', type: 'string' },
+        { name: '1starts-with-digit', type: 'string' },
+        { name: 'has.dot', type: 'string' },
+      ],
+    };
+    const errors = errorsFor(task({ id: 'a', ports }));
+    const msgs = portsErrors(errors).map((e) => e.message);
+    expect(msgs.filter((m) => /port name .* is invalid/.test(m)).length).toBe(3);
+  });
+
+  test('flags duplicate port names within the same list', () => {
+    const ports: TaskPorts = {
+      inputs: [
+        { name: 'x', type: 'string' },
+        { name: 'x', type: 'number' },
+      ],
+    };
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /Duplicate ports\.inputs name/.test(e.message))).toBe(
+      true,
+    );
+  });
+
+  test('rejects unknown port type', () => {
+    const ports = { inputs: [{ name: 'x', type: 'made-up' as never }] } as TaskPorts;
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /type must be one of/.test(e.message))).toBe(true);
+  });
+
+  test('enum port requires a non-empty enum array', () => {
+    const ports: TaskPorts = { inputs: [{ name: 'x', type: 'enum' }] };
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /non-empty "enum"/.test(e.message))).toBe(true);
+  });
+
+  test('enum values must all be strings', () => {
+    const ports = {
+      inputs: [{ name: 'x', type: 'enum' as const, enum: ['a', 1 as unknown as string] }],
+    } as TaskPorts;
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /enum values must all be strings/.test(e.message))).toBe(
+      true,
+    );
+  });
+
+  test('`from` must be a string', () => {
+    const ports = {
+      inputs: [
+        { name: 'x', type: 'string' as const, from: 42 as unknown as string },
+      ],
+    } as TaskPorts;
+    const errors = errorsFor(task({ id: 'a', ports }));
+    expect(portsErrors(errors).some((e) => /"from" must be a string/.test(e.message))).toBe(true);
+  });
+});
+
+// ─── Input/output separation ─────────────────────────────────────────
+
+describe('validateRaw — input vs output constraints', () => {
+  test('`required` on an output emits a warning (not an error)', () => {
+    const ports: TaskPorts = {
+      outputs: [{ name: 'x', type: 'string', required: true }],
+    };
+    const errors = errorsFor(task({ id: 'a', ports, prompt: 'x' }));
+    const portErrs = portsErrors(errors);
+    expect(portErrs.length).toBeGreaterThan(0);
+    expect(portErrs[0]!.severity).toBe('warning');
+    expect(portErrs[0]!.message).toMatch(/input-only/);
+  });
+
+  test('`from` on an output also warns', () => {
+    const ports: TaskPorts = {
+      outputs: [{ name: 'x', type: 'string', from: 'whatever' }],
+    };
+    const errors = errorsFor(task({ id: 'a', ports }));
+    const portErrs = portsErrors(errors);
+    expect(portErrs[0]!.severity).toBe('warning');
+  });
+});
+
+// ─── {{inputs.X}} cross-check ────────────────────────────────────────
+
+describe('validateRaw — placeholder cross-check', () => {
+  test('references to undeclared inputs in prompt are errors', () => {
+    const errors = errorsFor(
+      task({
+        id: 'a',
+        prompt: 'city={{inputs.city}} id={{inputs.id}}',
+        ports: { inputs: [{ name: 'city', type: 'string' }] },
+      }),
+    );
+    const msgs = errors.map((e) => e.message);
+    expect(msgs.some((m) => m.includes('references "{{inputs.id}}"'))).toBe(true);
+    expect(msgs.some((m) => m.includes('references "{{inputs.city}}"'))).toBe(false);
+  });
+
+  test('references to undeclared inputs in command are errors', () => {
+    const errors = errorsFor(
+      task({
+        id: 'a',
+        prompt: undefined,
+        command: 'echo {{inputs.oops}}',
+      }),
+    );
+    expect(errors.some((e) => e.message.includes('references "{{inputs.oops}}"'))).toBe(true);
+  });
+
+  test('declared inputs with no references emit a warning for command tasks', () => {
+    const errors = errorsFor(
+      task({
+        id: 'a',
+        prompt: undefined,
+        command: 'echo hi',
+        ports: { inputs: [{ name: 'unused', type: 'string' }] },
+      }),
+    );
+    const warnings = errors.filter(
+      (e) => e.severity === 'warning' && /declared input is unused/.test(e.message),
+    );
+    expect(warnings.length).toBe(1);
+  });
+
+  test('declared inputs with no references do NOT warn for prompt tasks', () => {
+    // Prompt tasks consume inputs through the auto-injected [Inputs]
+    // context block, so "unused" is a false alarm for them. Only command
+    // tasks should see the unused-input warning.
+    const errors = errorsFor(
+      task({
+        id: 'a',
+        prompt: 'do the thing',
+        ports: { inputs: [{ name: 'context', type: 'string' }] },
+      }),
+    );
+    const warnings = errors.filter(
+      (e) => e.severity === 'warning' && /declared input is unused/.test(e.message),
+    );
+    expect(warnings.length).toBe(0);
+  });
+});

package/src/validate-raw.ts

@@ -6,7 +6,7 @@
 //
 // Returns a flat list of ValidationError objects. An empty array means valid.
 
-import type { RawPipelineConfig } from './types';
+import type { PortDef, PortType, RawPipelineConfig, RawTaskConfig } from './types';
 import {
   isValidTaskId,
   qualifyTaskId,
@@ -14,6 +14,7 @@ import {
   resolveTaskRef,
   type TaskIndex,
 } from './task-ref';
+import { extractInputReferences } from './ports';
 
 const DURATION_RE = /^(\d*\.?\d+)\s*(s|m|h|d)$/;
 function isValidDuration(input: string): boolean {
@@ -284,6 +285,9 @@ export function validateRaw(
         }
       }
 
+      // ── Port declaration checks ──
+      validateTaskPorts(task, taskPath, errors);
+
       // ── depends_on reference checks ──
       if (task.depends_on && task.depends_on.length > 0) {
         for (const dep of task.depends_on) {
@@ -343,6 +347,156 @@ export function validateRaw(
   return errors;
 }
 
+const VALID_PORT_TYPES: ReadonlySet<PortType> = new Set([
+  'string',
+  'number',
+  'boolean',
+  'enum',
+  'json',
+]);
+
+// Identifier pattern for port names. Deliberately narrower than task IDs —
+// port names appear in `{{inputs.<name>}}` templates where hyphens would
+// be parsed as subtraction, so we also forbid them here to keep the
+// template grammar unambiguous.
+const PORT_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function validatePortList(
+  list: readonly PortDef[] | undefined,
+  basePath: string,
+  kind: 'inputs' | 'outputs',
+  errors: ValidationError[],
+): void {
+  if (!list) return;
+  if (!Array.isArray(list)) {
+    errors.push({
+      path: basePath,
+      message: `ports.${kind} must be an array`,
+    });
+    return;
+  }
+  const seen = new Set<string>();
+  for (let i = 0; i < list.length; i++) {
+    const port = list[i];
+    const path = `${basePath}[${i}]`;
+    if (!port || typeof port !== 'object') {
+      errors.push({ path, message: `ports.${kind}[${i}] must be an object` });
+      continue;
+    }
+    if (typeof port.name !== 'string' || !port.name.trim()) {
+      errors.push({ path: `${path}.name`, message: 'port.name is required' });
+      continue;
+    }
+    if (!PORT_NAME_RE.test(port.name)) {
+      errors.push({
+        path: `${path}.name`,
+        message: `port name "${port.name}" is invalid. Must match /^[A-Za-z_][A-Za-z0-9_]*$/ (letters, digits, underscores; starts with letter/underscore).`,
+      });
+    }
+    if (seen.has(port.name)) {
+      errors.push({
+        path,
+        message: `Duplicate ports.${kind} name "${port.name}"`,
+      });
+    }
+    seen.add(port.name);
+    if (!VALID_PORT_TYPES.has(port.type)) {
+      errors.push({
+        path: `${path}.type`,
+        message: `port "${port.name}": type must be one of ${[...VALID_PORT_TYPES].join(', ')} (got ${JSON.stringify(port.type)})`,
+      });
+    }
+    if (port.type === 'enum') {
+      if (!Array.isArray(port.enum) || port.enum.length === 0) {
+        errors.push({
+          path: `${path}.enum`,
+          message: `port "${port.name}": enum type requires a non-empty "enum" array`,
+        });
+      } else if (port.enum.some((v: unknown) => typeof v !== 'string')) {
+        errors.push({
+          path: `${path}.enum`,
+          message: `port "${port.name}": enum values must all be strings`,
+        });
+      }
+    }
+    if (kind === 'outputs' && (port.required === true || port.from !== undefined)) {
+      // `required` / `from` are input-only concepts — outputs are
+      // always "produced when the task succeeds". Warn softly so the
+      // YAML doesn't silently accept meaningless fields.
+      errors.push({
+        path,
+        severity: 'warning',
+        message: `port "${port.name}": "required" and "from" are input-only; ignored on outputs`,
+      });
+    }
+    if (port.from !== undefined && typeof port.from !== 'string') {
+      errors.push({
+        path: `${path}.from`,
+        message: `port "${port.name}": "from" must be a string (got ${typeof port.from})`,
+      });
+    }
+  }
+}
+
+function validateTaskPorts(
+  task: RawTaskConfig,
+  taskPath: string,
+  errors: ValidationError[],
+): void {
+  const ports = task.ports;
+  // Placeholder cross-checks are independent of ports being declared —
+  // a user can type `{{inputs.X}}` without declaring any ports yet, and
+  // that's always an error (the engine has no `X` to substitute, and
+  // `validate-raw` is the one place that surfaces this before a run).
+  // Running the check unconditionally catches the typo on its own.
+  const declaredInputs = new Set<string>(
+    ports && Array.isArray(ports.inputs)
+      ? ports.inputs.filter((p): p is PortDef => !!p && typeof p === 'object').map((p) => p.name)
+      : [],
+  );
+  const referenced = new Set<string>();
+  if (typeof task.prompt === 'string') {
+    for (const n of extractInputReferences(task.prompt)) referenced.add(n);
+  }
+  if (typeof task.command === 'string') {
+    for (const n of extractInputReferences(task.command)) referenced.add(n);
+  }
+  for (const name of referenced) {
+    if (!declaredInputs.has(name)) {
+      errors.push({
+        path: taskPath,
+        message: `Task "${task.id}": references "{{inputs.${name}}}" but no such input port is declared`,
+      });
+    }
+  }
+
+  if (!ports) return;
+
+  // Per-port structural validation runs only after we've established
+  // that `ports.inputs` / `ports.outputs` are arrays — validatePortList
+  // also re-checks Array.isArray internally, which keeps it callable
+  // from contexts that hand it stray values.
+  validatePortList(ports.inputs, `${taskPath}.ports.inputs`, 'inputs', errors);
+  validatePortList(ports.outputs, `${taskPath}.ports.outputs`, 'outputs', errors);
+
+  // Warn on declared-but-unused inputs. Not fatal — a user may want to
+  // surface an input as a data-flow hint for the editor even when the
+  // prompt/command doesn't template it explicitly (e.g. AI tasks that
+  // consume inputs through the `[Inputs]` context block).
+  if (typeof task.command === 'string' && Array.isArray(ports.inputs)) {
+    for (const port of ports.inputs) {
+      if (!port || typeof port !== 'object') continue;
+      if (!referenced.has(port.name)) {
+        errors.push({
+          path: `${taskPath}.ports.inputs`,
+          severity: 'warning',
+          message: `Task "${task.id}": command does not reference {{inputs.${port.name}}} — declared input is unused`,
+        });
+      }
+    }
+  }
+}
+
 function detectCycles(config: RawPipelineConfig, index: TaskIndex): ValidationError[] {
   // Build adjacency: qualifiedId → [resolved dep qualifiedIds]
   const adj = new Map<string, string[]>();