@tagma/sdk 0.6.11 → 0.6.12

package/src/schema-ports.test.ts

@@ -13,6 +13,34 @@ 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', () => {
+    const raw: RawPipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'a',
+              command: 'echo "{{inputs.city}}"',
+              inputs: {
+                city: { from: 't.plan.outputs.city', required: true },
+              },
+              outputs: {
+                report: { from: 'json.reportPath' },
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const resolved = resolveConfig(raw, WORK_DIR);
+    const task = resolved.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',
@@ -83,6 +111,35 @@ describe('resolveConfig — ports passthrough', () => {
 // ─── deresolvePipeline preserves ports ───────────────────────────────
 
 describe('deresolvePipeline — ports round-trip', () => {
+  test('lightweight bindings round-trip', () => {
+    const raw: RawPipelineConfig = {
+      name: 'p',
+      tracks: [
+        {
+          id: 't',
+          name: 'T',
+          tasks: [
+            {
+              id: 'a',
+              command: 'echo "{{inputs.city}}"',
+              inputs: {
+                city: { from: 't.plan.outputs.city', required: true },
+                mode: { default: 'quick' },
+              },
+              outputs: {
+                raw: { from: 'stdout' },
+              },
+            },
+          ],
+        },
+      ],
+    };
+    const resolved = resolveConfig(raw, WORK_DIR);
+    const back = deresolvePipeline(resolved, 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',
@@ -200,6 +257,35 @@ describe('deresolvePipeline — ports round-trip', () => {
 // ─── parseYaml accepts ports ─────────────────────────────────────────
 
 describe('parseYaml — accepts ports declarations', () => {
+  test('real-world YAML with lightweight bindings parses cleanly', () => {
+    const text = `pipeline:
+  name: demo
+  tracks:
+    - id: t
+      name: Main
+      tasks:
+        - id: build
+          command: bun run build
+          outputs:
+            bundlePath: { from: json.bundlePath }
+        - id: test
+          depends_on: [build]
+          command: 'bun test "{{inputs.bundlePath}}"'
+          inputs:
+            bundlePath:
+              from: t.build.outputs.bundlePath
+              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({
+      from: 't.build.outputs.bundlePath',
+      required: true,
+    });
+  });
+
   test('real-world YAML with ports parses cleanly', () => {
     const text = `pipeline:
   name: demo

package/src/schema.ts

@@ -97,7 +97,7 @@ function validateRawTask(task: RawTaskConfig, trackId: string): void {
     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 non-fatal validation errors by validate-raw.ts.
+  // flagged as hard validation errors by validate-raw.ts.
 }
 
 // ═══ Config Inheritance Resolution ═══
@@ -161,8 +161,10 @@ 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`).
+        // Lightweight bindings and ports: no inheritance — they describe
+        // per-task data flow, not cross-task defaults.
+        inputs: rawTask.inputs,
+        outputs: rawTask.outputs,
         ports: rawTask.ports,
       };
     });
@@ -309,6 +311,8 @@ export function deresolvePipeline(config: PipelineConfig, workDir: string): RawP
         ...(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 } : {}),
         ...(task.ports &&
         ((task.ports.inputs && task.ports.inputs.length > 0) ||
           (task.ports.outputs && task.ports.outputs.length > 0))

package/src/sdk.ts

@@ -129,12 +129,16 @@ export {
 export {
   substituteInputs,
   extractInputReferences,
+  resolveTaskBindingInputs,
   resolveTaskInputs,
+  extractTaskBindingOutputs,
   extractTaskOutputs,
   inferPromptPorts,
 } from './ports';
 export type {
   SubstituteResult,
+  BindingInputResolution,
+  UpstreamBindingData,
   InputResolution,
   ExtractResult,
   PromptPortInference,

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

@@ -38,6 +38,12 @@ function portsErrors(errors: ReturnType<typeof validateRaw>): typeof errors {
   );
 }
 
+function bindingErrors(errors: ReturnType<typeof validateRaw>): typeof errors {
+  return errors.filter(
+    (e) => e.path.includes('.inputs') || e.path.includes('.outputs'),
+  );
+}
+
 // ─── Structural validation (Command Tasks) ───────────────────────────
 
 describe('validateRaw — port structure (command tasks)', () => {
@@ -123,6 +129,66 @@ describe('validateRaw — port structure (command tasks)', () => {
   });
 });
 
+// ─── Lightweight binding validation ──────────────────────────────────
+
+describe('validateRaw — lightweight task bindings', () => {
+  test('accepts top-level inputs for command placeholder references', () => {
+    const errors = errorsFor(
+      commandTask({
+        id: 'a',
+        command: 'echo {{inputs.city}}',
+        inputs: { city: { value: 'Shanghai' } },
+      }),
+    );
+    expect(errors.some((e) => e.message.includes('references "{{inputs.city}}"'))).toBe(false);
+  });
+
+  test('rejects non-object binding maps and entries', () => {
+    const errors = errorsFor(
+      commandTask({
+        id: 'a',
+        inputs: 'bad' as unknown as never,
+        outputs: { ok: 'bad' as unknown as never },
+      }),
+    );
+    const msgs = bindingErrors(errors).map((e) => e.message);
+    expect(msgs.some((m) => /task\.inputs must be an object/.test(m))).toBe(true);
+    expect(msgs.some((m) => /task\.outputs\.ok must be an object/.test(m))).toBe(true);
+  });
+
+  test('rejects invalid binding names and duplicate loose/strict names', () => {
+    const errors = errorsFor(
+      commandTask({
+        id: 'a',
+        inputs: { 'bad-name': { value: 'x' }, city: { value: 'Shanghai' } },
+        outputs: { report: { from: 'stdout' } },
+        ports: {
+          inputs: [{ name: 'city', type: 'string' }],
+          outputs: [{ name: 'report', type: 'string' }],
+        },
+      }),
+    );
+    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) => /duplicates strict ports\.inputs/.test(m))).toBe(true);
+    expect(msgs.some((m) => /duplicates strict ports\.outputs/.test(m))).toBe(true);
+  });
+
+  test('fully-qualified binding sources must reference direct dependencies', () => {
+    const errors = validateRaw(
+      pipeline([
+        commandTask({ id: 'up', outputs: { city: {} } }),
+        commandTask({
+          id: 'down',
+          depends_on: [],
+          inputs: { city: { from: 't.up.outputs.city', required: true } },
+        }),
+      ]),
+    );
+    expect(errors.some((e) => /not a direct dependency/.test(e.message))).toBe(true);
+  });
+});
+
 // ─── Input/output separation (Command Tasks) ─────────────────────────
 
 describe('validateRaw — input vs output constraints (command tasks)', () => {

package/src/validate-raw.ts

@@ -538,6 +538,136 @@ function validatePortList(
   }
 }
 
+function validateBindingMap(
+  value: unknown,
+  basePath: string,
+  kind: 'inputs' | 'outputs',
+  errors: ValidationError[],
+): void {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push({ path: basePath, message: `task.${kind} must be an object map` });
+    return;
+  }
+
+  const map = value as Record<string, unknown>;
+  for (const [name, rawBinding] of Object.entries(map)) {
+    const path = `${basePath}.${name}`;
+    if (!PORT_NAME_RE.test(name)) {
+      errors.push({
+        path,
+        message: `binding name "${name}" is invalid. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,
+      });
+    }
+    if (!rawBinding || typeof rawBinding !== 'object' || Array.isArray(rawBinding)) {
+      errors.push({ path, message: `task.${kind}.${name} must be an object` });
+      continue;
+    }
+    const binding = rawBinding as Record<string, unknown>;
+    if ('from' in binding && typeof binding.from !== 'string') {
+      errors.push({ path: `${path}.from`, message: `task.${kind}.${name}.from must be a string` });
+    }
+    if (kind === 'inputs' && 'required' in binding && typeof binding.required !== 'boolean') {
+      errors.push({
+        path: `${path}.required`,
+        message: `task.inputs.${name}.required must be a boolean`,
+      });
+    }
+    if (kind === 'outputs' && typeof binding.from === 'string') {
+      const source = binding.from;
+      const ok =
+        source === 'stdout' ||
+        source === 'stderr' ||
+        source === 'normalizedOutput' ||
+        /^json\.[A-Za-z_][A-Za-z0-9_]*$/.test(source);
+      if (!ok) {
+        errors.push({
+          path: `${path}.from`,
+          message: `task.outputs.${name}.from must be stdout, stderr, normalizedOutput, or json.<key>`,
+        });
+      }
+    }
+  }
+}
+
+function validateBindingPortNameOverlap(
+  task: RawTaskConfig,
+  taskPath: string,
+  errors: ValidationError[],
+): void {
+  const looseInputs = objectKeys(task.inputs);
+  const looseOutputs = objectKeys(task.outputs);
+  const strictInputs = new Set(
+    Array.isArray(task.ports?.inputs) ? task.ports.inputs.map((p) => p?.name) : [],
+  );
+  const strictOutputs = new Set(
+    Array.isArray(task.ports?.outputs) ? task.ports.outputs.map((p) => p?.name) : [],
+  );
+
+  for (const name of looseInputs) {
+    if (strictInputs.has(name)) {
+      errors.push({
+        path: `${taskPath}.inputs.${name}`,
+        message: `task input binding "${name}" duplicates strict ports.inputs; choose one layer for this name`,
+      });
+    }
+  }
+  for (const name of looseOutputs) {
+    if (strictOutputs.has(name)) {
+      errors.push({
+        path: `${taskPath}.outputs.${name}`,
+        message: `task output binding "${name}" duplicates strict ports.outputs; choose one layer for this name`,
+      });
+    }
+  }
+}
+
+function objectKeys(value: unknown): string[] {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return [];
+  return Object.keys(value as Record<string, unknown>);
+}
+
+function validateInputBindingSources(
+  task: RawTaskConfig,
+  trackId: string,
+  taskPath: string,
+  index: TaskIndex,
+  errors: ValidationError[],
+): void {
+  if (!task.inputs || typeof task.inputs !== 'object' || Array.isArray(task.inputs)) return;
+  for (const [name, rawBinding] of Object.entries(task.inputs)) {
+    if (!rawBinding || typeof rawBinding !== 'object' || Array.isArray(rawBinding)) continue;
+    const source = (rawBinding as Record<string, unknown>).from;
+    if (typeof source !== 'string') continue;
+    const upstreamId = bindingSourceTaskId(source);
+    if (!upstreamId) continue;
+    const deps = task.depends_on ?? [];
+    const isDirectDep = deps.some((dep) => {
+      const resolved = resolveTaskRef(dep, trackId, index);
+      return resolved.kind === 'resolved' && resolved.qid === upstreamId;
+    });
+    if (!isDirectDep) {
+      errors.push({
+        path: `${taskPath}.inputs.${name}.from`,
+        message: `Task "${task.id}": input binding "${name}" from "${source}" references task "${upstreamId}" which is not a direct dependency (must be listed in depends_on)`,
+      });
+    }
+  }
+}
+
+function bindingSourceTaskId(source: string): string | null {
+  const outputMarker = '.outputs.';
+  const outputIdx = source.lastIndexOf(outputMarker);
+  if (outputIdx > 0) return source.slice(0, outputIdx);
+  for (const field of ['stdout', 'stderr', 'normalizedOutput', 'exitCode']) {
+    const suffix = `.${field}`;
+    if (source.endsWith(suffix) && source.length > suffix.length) {
+      return source.slice(0, -suffix.length);
+    }
+  }
+  return null;
+}
+
 function validateTaskPorts(
   task: RawTaskConfig,
   trackId: string,
@@ -550,6 +680,11 @@ function validateTaskPorts(
   const isPromptTask = typeof task.prompt === 'string' && typeof task.command !== 'string';
   const isCommandTask = typeof task.command === 'string' && typeof task.prompt !== 'string';
 
+  validateBindingMap(task.inputs, `${taskPath}.inputs`, 'inputs', errors);
+  validateBindingMap(task.outputs, `${taskPath}.outputs`, 'outputs', errors);
+  validateBindingPortNameOverlap(task, taskPath, errors);
+  validateInputBindingSources(task, trackId, taskPath, index, errors);
+
   // ─── Prompt tasks do not declare ports ──
   //
   // A Prompt Task's I/O contract is inferred from direct-neighbor
@@ -585,6 +720,7 @@ function validateTaskPorts(
   let availableInputs: Set<string>;
   if (isPromptTask) {
     availableInputs = collectUpstreamCommandOutputNames(task, trackId, qidIndex, index);
+    for (const name of objectKeys(task.inputs)) availableInputs.add(name);
   } else {
     // Command Task (or the pathological both-keys case, which is caught
     // earlier as a separate error — tolerate it here).
@@ -593,6 +729,7 @@ function validateTaskPorts(
         ? ports.inputs.filter((p): p is PortDef => !!p && typeof p === 'object').map((p) => p.name)
         : [],
     );
+    for (const name of objectKeys(task.inputs)) availableInputs.add(name);
   }
 
   for (const name of referenced) {