@tagma/sdk 0.6.10 → 0.6.12

package/src/utils.test.ts

@@ -0,0 +1,28 @@
+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,4 +1,4 @@
-import { resolve, relative, parse as parsePath } from 'path';
+import { isAbsolute, resolve, relative, parse as parsePath, sep } from 'path';
 import { realpathSync, lstatSync, existsSync } from 'fs';
 import { randomBytes } from 'crypto';
 
@@ -38,7 +38,7 @@ export function validatePath(filePath: string, projectRoot: string): string {
   }
 
   const rel = relative(projectRoot, resolved);
-  if (rel.startsWith('..') || rel.startsWith('/')) {
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(
       `Security: path "${filePath}" escapes project root. ` +
         `All file references must be within "${projectRoot}".`,
@@ -83,7 +83,7 @@ export function validatePath(filePath: string, projectRoot: string): string {
       );
     }
     const realRel = relative(realRoot, real);
-    if (realRel.startsWith('..') || realRel.startsWith('/')) {
+    if (realRel === '..' || realRel.startsWith(`..${sep}`) || isAbsolute(realRel)) {
       throw new Error(
         `Security: path "${filePath}" resolves via symlink to "${real}" which escapes project root "${realRoot}".`,
       );

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

@@ -32,6 +32,7 @@ function buildQidIndex(config: RawPipelineConfig): Map<string, QidEntry> {
   const idx = new Map<string, QidEntry>();
   for (const track of config.tracks ?? []) {
     if (!track.id) continue;
+    if (!Array.isArray(track.tasks)) continue;
     for (const task of track.tasks ?? []) {
       if (!task.id) continue;
       idx.set(qualifyTaskId(track.id, task.id), { track, task });
@@ -55,6 +56,7 @@ const isValidId = isValidTaskId;
 
 const VALID_ON_FAILURE = new Set(['skip_downstream', 'stop_all', 'ignore']);
 const VALID_REASONING_EFFORT = new Set(['low', 'medium', 'high']);
+const PERMISSION_FIELDS = ['read', 'write', 'execute'] as const;
 
 // Built-in plugin types always known to the SDK core, regardless of which
 // external plugin packages are installed. These MUST stay in sync with the
@@ -150,8 +152,13 @@ export function validateRaw(
       severity: 'warning',
     });
   }
+  validatePermissions(config.permissions, 'permissions', errors);
 
-  if (!config.tracks || config.tracks.length === 0) {
+  if (!Array.isArray(config.tracks)) {
+    errors.push({ path: 'tracks', message: 'pipeline.tracks must be an array' });
+    return errors;
+  }
+  if (config.tracks.length === 0) {
     errors.push({ path: 'tracks', message: 'At least one track is required' });
     return errors; // No point going further without tracks
   }
@@ -168,8 +175,13 @@ export function validateRaw(
   // ── Per-track validation ──
   const seenTrackIds = new Set<string>();
   for (let ti = 0; ti < config.tracks.length; ti++) {
-    const track = config.tracks[ti];
+    const maybeTrack = config.tracks[ti] as unknown;
     const trackPath = `tracks[${ti}]`;
+    if (!maybeTrack || typeof maybeTrack !== 'object' || Array.isArray(maybeTrack)) {
+      errors.push({ path: trackPath, message: `Track ${ti} must be an object` });
+      continue;
+    }
+    const track = maybeTrack as RawTrackConfig;
 
     if (!track.id?.trim()) {
       errors.push({ path: `${trackPath}.id`, message: 'Track id is required' });
@@ -205,6 +217,7 @@ export function validateRaw(
         severity: 'warning',
       });
     }
+    validatePermissions(track.permissions, `${trackPath}.permissions`, errors);
 
     // Track-level middlewares can reference a plugin that was uninstalled
     // after the YAML was written — surface a warning so the user notices
@@ -222,7 +235,14 @@ export function validateRaw(
       }
     }
 
-    if (!track.tasks || track.tasks.length === 0) {
+    if (!Array.isArray(track.tasks)) {
+      errors.push({
+        path: `${trackPath}.tasks`,
+        message: `Track "${track.id || ti}": tasks must be an array`,
+      });
+      continue;
+    }
+    if (track.tasks.length === 0) {
       errors.push({
         path: `${trackPath}.tasks`,
         message: `Track "${track.id || ti}": must have at least one task`,
@@ -302,6 +322,7 @@ export function validateRaw(
           severity: 'warning',
         });
       }
+      validatePermissions(task.permissions, `${taskPath}.permissions`, errors);
 
       // ── Plugin type warnings (trigger / completion / middlewares) ──
       // Only fire when the host supplied a `knownTypes` snapshot, so offline
@@ -374,7 +395,7 @@ export function validateRaw(
           });
         } else if (
           !task.depends_on ||
-          !task.depends_on.some((dep) => {
+          !task.depends_on.some((dep: string) => {
             const depResolved = resolveTaskRef(dep, track.id, index);
             return depResolved.kind === 'resolved' && depResolved.qid === resolved.qid;
           })
@@ -400,6 +421,32 @@ export function validateRaw(
   return errors;
 }
 
+function validatePermissions(
+  value: unknown,
+  basePath: string,
+  errors: ValidationError[],
+): void {
+  if (value === undefined) return;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push({
+      path: basePath,
+      message: 'permissions must be an object with read/write/execute booleans',
+    });
+    return;
+  }
+  const p = value as Record<string, unknown>;
+  for (const field of PERMISSION_FIELDS) {
+    const path = `${basePath}.${field}`;
+    if (!(field in p)) {
+      errors.push({ path, message: `permissions.${field} is required` });
+      continue;
+    }
+    if (typeof p[field] !== 'boolean') {
+      errors.push({ path, message: `permissions.${field} must be a boolean` });
+    }
+  }
+}
+
 const VALID_PORT_TYPES: ReadonlySet<PortType> = new Set([
   'string',
   'number',
@@ -491,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,
@@ -503,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
@@ -538,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).
@@ -546,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) {
@@ -764,6 +948,7 @@ function detectCycles(config: RawPipelineConfig, index: TaskIndex): ValidationEr
 
   for (const track of config.tracks) {
     if (!track.id) continue;
+    if (!Array.isArray(track.tasks)) continue;
     for (const task of track.tasks ?? []) {
       if (!task.id) continue;
       const qid = qualifyTaskId(track.id, task.id);

package/src/yaml-compiler.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from 'bun:test';
+import { compileYamlContent } from './yaml-compiler';
+
+describe('compileYamlContent', () => {
+  test('reports YAML syntax failures as parse errors', () => {
+    const result = compileYamlContent('pipeline:\n  name: [');
+
+    expect(result.parseOk).toBe(false);
+    expect(result.success).toBe(false);
+    expect(result.validation.errors).toEqual([]);
+    expect(result.summary).toMatch(/^YAML parse error:/);
+  });
+
+  test('reports missing top-level pipeline as a validation error', () => {
+    const result = compileYamlContent('name: Missing Pipeline\n');
+
+    expect(result.parseOk).toBe(true);
+    expect(result.success).toBe(false);
+    expect(result.validation.errors).toEqual([
+      { path: 'pipeline', message: 'Top-level "pipeline" key is required' },
+    ]);
+    expect(result.summary).toBe('Invalid: 1 error(s), 0 warning(s)');
+  });
+
+  test('reports non-array tracks as a validation error, not a parse failure', () => {
+    const result = compileYamlContent(`
+pipeline:
+  name: Bad
+  tracks:
+    id: not-an-array
+`);
+
+    expect(result.parseOk).toBe(true);
+    expect(result.success).toBe(false);
+    expect(result.validation.errors).toEqual([
+      { path: 'tracks', message: 'pipeline.tracks must be an array' },
+    ]);
+  });
+
+  test('reports non-array task lists as validation errors, not validation crashes', () => {
+    const result = compileYamlContent(`
+pipeline:
+  name: Bad Tasks
+  tracks:
+    - id: t
+      name: T
+      tasks:
+        id: not-an-array
+`);
+
+    expect(result.parseOk).toBe(true);
+    expect(result.success).toBe(false);
+    expect(result.validation.errors).toEqual([
+      { path: 'tracks[0].tasks', message: 'Track "t": tasks must be an array' },
+    ]);
+    expect(result.summary).not.toMatch(/Validation crashed/);
+  });
+
+  test('routes schema errors through validation when YAML syntax is valid', () => {
+    const result = compileYamlContent(`
+pipeline:
+  name: Missing Track Name
+  tracks:
+    - id: main
+      tasks:
+        - id: task
+          prompt: hello
+`);
+
+    expect(result.parseOk).toBe(true);
+    expect(result.success).toBe(false);
+    expect(result.validation.errors).toContainEqual({
+      path: 'tracks[0].name',
+      message: 'Track name is required',
+    });
+  });
+
+  test('validates pipeline, track, and task permissions shape', () => {
+    const result = compileYamlContent(`
+pipeline:
+  name: Bad Permissions
+  permissions: { read: true, write: "yes", execute: false }
+  tracks:
+    - id: main
+      name: Main
+      permissions: { read: true, execute: false }
+      tasks:
+        - id: task
+          prompt: hello
+          permissions: nope
+`);
+
+    expect(result.parseOk).toBe(true);
+    expect(result.success).toBe(false);
+    expect(result.validation.errors).toContainEqual({
+      path: 'permissions.write',
+      message: 'permissions.write must be a boolean',
+    });
+    expect(result.validation.errors).toContainEqual({
+      path: 'tracks[0].permissions.write',
+      message: 'permissions.write is required',
+    });
+    expect(result.validation.errors).toContainEqual({
+      path: 'tracks[0].tasks[0].permissions',
+      message: 'permissions must be an object with read/write/execute booleans',
+    });
+  });
+});

package/src/yaml-compiler.ts

@@ -1,4 +1,4 @@
-import { parseYaml } from './schema';
+import yaml from 'js-yaml';
 import { validateRaw } from './validate-raw';
 import type { ValidationError, KnownPluginTypes } from './validate-raw';
 import type { RawPipelineConfig } from './types';
@@ -27,9 +27,9 @@ export function compileYamlContent(
   const timestamp = new Date().toISOString();
   const sourceName = opts.sourceName ?? 'untitled';
 
-  let config: RawPipelineConfig;
+  let doc: unknown;
   try {
-    config = parseYaml(content);
+    doc = yaml.load(content);
   } catch (err) {
     return {
       timestamp,
@@ -41,6 +41,12 @@ export function compileYamlContent(
     };
   }
 
+  const envelopeErrors = validateEnvelope(doc);
+  if (envelopeErrors.length > 0) {
+    return buildValidationResult(timestamp, sourceName, envelopeErrors);
+  }
+  const config = (doc as { pipeline: RawPipelineConfig }).pipeline;
+
   let errors: ValidationError[];
   try {
     errors = validateRaw(config, opts.knownTypes);
@@ -55,8 +61,29 @@ export function compileYamlContent(
     };
   }
 
-  const validationErrors = errors.filter((e) => e.severity === 'error' || e.severity == null);
-  const validationWarnings = errors.filter((e) => e.severity === 'warning');
+  return buildValidationResult(timestamp, sourceName, errors);
+}
+
+function validateEnvelope(doc: unknown): ValidationError[] {
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc) || !('pipeline' in doc)) {
+    return [{ path: 'pipeline', message: 'Top-level "pipeline" key is required' }];
+  }
+  const pipeline = (doc as Record<string, unknown>).pipeline;
+  if (!pipeline || typeof pipeline !== 'object' || Array.isArray(pipeline)) {
+    return [{ path: 'pipeline', message: 'pipeline must be an object' }];
+  }
+  return [];
+}
+
+function buildValidationResult(
+  timestamp: string,
+  sourceName: string,
+  diagnostics: readonly ValidationError[],
+): YamlCompileResult {
+  const validationErrors = diagnostics.filter(
+    (e) => e.severity === 'error' || e.severity == null,
+  );
+  const validationWarnings = diagnostics.filter((e) => e.severity === 'warning');
 
   return {
     timestamp,