@tagma/sdk 0.6.9 → 0.6.11

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
@@ -67,6 +69,7 @@ const BUILTIN_COMPLETION_TYPES: ReadonlySet<string> = new Set([
   'output_check',
 ]);
 const BUILTIN_MIDDLEWARE_TYPES: ReadonlySet<string> = new Set(['static_context']);
+const BUILTIN_DRIVER_TYPES: ReadonlySet<string> = new Set(['opencode']);
 
 /**
  * Optional second argument to `validateRaw`: the set of plugin types currently
@@ -78,6 +81,7 @@ const BUILTIN_MIDDLEWARE_TYPES: ReadonlySet<string> = new Set(['static_context']
  * this argument and no plugin warnings will be produced.
  */
 export interface KnownPluginTypes {
+  readonly drivers?: readonly string[];
   readonly triggers?: readonly string[];
   readonly completions?: readonly string[];
   readonly middlewares?: readonly string[];
@@ -121,6 +125,9 @@ export function validateRaw(
   const knownTriggers = knownTypes
     ? new Set<string>([...BUILTIN_TRIGGER_TYPES, ...(knownTypes.triggers ?? [])])
     : null;
+  const knownDrivers = knownTypes
+    ? new Set<string>([...BUILTIN_DRIVER_TYPES, ...(knownTypes.drivers ?? [])])
+    : null;
   const knownCompletions = knownTypes
     ? new Set<string>([...BUILTIN_COMPLETION_TYPES, ...(knownTypes.completions ?? [])])
     : null;
@@ -138,8 +145,20 @@ export function validateRaw(
       message: `Invalid reasoning_effort "${config.reasoning_effort}". Expected "low", "medium", or "high".`,
     });
   }
+  if (knownDrivers && config.driver && !knownDrivers.has(config.driver)) {
+    errors.push({
+      path: 'driver',
+      message: `Unknown driver type "${config.driver}"`,
+      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
   }
@@ -156,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' });
@@ -186,6 +210,14 @@ export function validateRaw(
         message: `Invalid reasoning_effort "${track.reasoning_effort}". Expected "low", "medium", or "high".`,
       });
     }
+    if (knownDrivers && track.driver && !knownDrivers.has(track.driver)) {
+      errors.push({
+        path: `${trackPath}.driver`,
+        message: `Unknown driver type "${track.driver}"`,
+        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
@@ -203,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`,
@@ -276,6 +315,14 @@ export function validateRaw(
           message: `Invalid reasoning_effort "${task.reasoning_effort}". Expected "low", "medium", or "high".`,
         });
       }
+      if (knownDrivers && task.driver && !knownDrivers.has(task.driver)) {
+        errors.push({
+          path: `${taskPath}.driver`,
+          message: `Unknown driver type "${task.driver}"`,
+          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
@@ -348,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;
           })
@@ -374,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',
@@ -738,6 +811,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,