@tagma/sdk 0.7.4 → 0.7.5

package/src/tagma.ts

@@ -1,67 +0,0 @@
-import {
-  PluginRegistry,
-  runPipeline,
-  type EngineResult,
-  type RunPipelineOptions,
-} from '@tagma/core';
-import { bootstrapBuiltins } from './bootstrap';
-import { validateConfig } from './schema';
-import { bunRuntime } from '@tagma/runtime-bun';
-import type { TagmaRuntime } from '@tagma/core';
-import type { PipelineConfig, TagmaPlugin } 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;
-  /**
-   * Package-level capability plugins to register into this SDK instance.
-   */
-  readonly plugins?: readonly TagmaPlugin[];
-  /**
-   * Runtime implementation used for command and driver process execution.
-   * Defaults to the SDK's Bun runtime.
-   */
-  readonly runtime?: TagmaRuntime;
-}
-
-export interface TagmaRunOptions extends Omit<RunPipelineOptions, 'registry' | 'runtime'> {
-  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();
-  const runtime = options.runtime ?? bunRuntime();
-  if (options.builtins !== false) {
-    bootstrapBuiltins(registry);
-  }
-  for (const plugin of options.plugins ?? []) {
-    registry.registerTagmaPlugin(plugin);
-  }
-
-  return {
-    registry,
-    run(config, { cwd, ...runOptions }) {
-      return runPipeline(config, cwd, {
-        ...runOptions,
-        registry,
-        runtime,
-      });
-    },
-    validate(config) {
-      return validateConfig(config);
-    },
-  };
-}

package/src/task-ref.test.ts

@@ -1,401 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import type { PipelineConfig, RawPipelineConfig } from './types';
-import {
-  TASK_ID_RE,
-  isValidTaskId,
-  qualifyTaskId,
-  isQualifiedRef,
-  buildTaskIndex,
-  resolveTaskRef,
-  AMBIGUOUS,
-} from './task-ref';
-import { buildDag, buildRawDag } from './dag';
-import { validateRaw } from './validate-raw';
-
-// ═══ Low-level helpers ═══
-
-describe('isValidTaskId', () => {
-  test('accepts letter-led ids with letters, digits, underscores, hyphens', () => {
-    for (const id of ['a', 'A', '_', 'task_1', 'Task-2', '_private', 'a_b-c_1']) {
-      expect(isValidTaskId(id)).toBe(true);
-      expect(TASK_ID_RE.test(id)).toBe(true);
-    }
-  });
-
-  test('rejects empty, digit-led, dot-bearing, and whitespace forms', () => {
-    for (const id of ['', '1task', 'a.b', 'foo bar', '-leading', 'has/slash', 'dot.']) {
-      expect(isValidTaskId(id)).toBe(false);
-    }
-  });
-
-  test('rejects non-string values', () => {
-    expect(isValidTaskId(null as unknown as string)).toBe(false);
-    expect(isValidTaskId(undefined as unknown as string)).toBe(false);
-    expect(isValidTaskId(42 as unknown as string)).toBe(false);
-  });
-});
-
-describe('qualifyTaskId + isQualifiedRef', () => {
-  test('qualifyTaskId joins with dot; isQualifiedRef detects dotted form', () => {
-    expect(qualifyTaskId('alpha', 'review')).toBe('alpha.review');
-    expect(isQualifiedRef('alpha.review')).toBe(true);
-    expect(isQualifiedRef('review')).toBe(false);
-  });
-});
-
-// ═══ Index build ═══
-
-describe('buildTaskIndex', () => {
-  test('collects all qualified ids and unique bare ids', () => {
-    const cfg: RawPipelineConfig = {
-      name: 'T',
-      tracks: [
-        { id: 'alpha', name: 'A', tasks: [{ id: 'plan', prompt: 'p' }] },
-        { id: 'beta', name: 'B', tasks: [{ id: 'ship', prompt: 'p' }] },
-      ],
-    };
-    const idx = buildTaskIndex(cfg);
-    expect(idx.allQualified.has('alpha.plan')).toBe(true);
-    expect(idx.allQualified.has('beta.ship')).toBe(true);
-    expect(idx.bareToQualified.get('plan')).toBe('alpha.plan');
-    expect(idx.bareToQualified.get('ship')).toBe('beta.ship');
-  });
-
-  test('marks bare ids shared across tracks as ambiguous', () => {
-    const cfg: RawPipelineConfig = {
-      name: 'T',
-      tracks: [
-        { id: 'alpha', name: 'A', tasks: [{ id: 'review', prompt: 'p' }] },
-        { id: 'beta', name: 'B', tasks: [{ id: 'review', prompt: 'p' }] },
-      ],
-    };
-    const idx = buildTaskIndex(cfg);
-    expect(idx.bareToQualified.get('review')).toBe(AMBIGUOUS);
-    expect(idx.allQualified.has('alpha.review')).toBe(true);
-    expect(idx.allQualified.has('beta.review')).toBe(true);
-  });
-
-  test('tolerates tracks/tasks missing ids (editor in-progress state)', () => {
-    const cfg = {
-      name: 'T',
-      tracks: [
-        { id: '', name: 'half-typed', tasks: [{ id: 'x', prompt: 'p' }] },
-        { id: 'ok', name: 'OK', tasks: [{ id: '', prompt: 'p' }, { id: 'y', prompt: 'p' }] },
-      ],
-    } as unknown as RawPipelineConfig;
-    const idx = buildTaskIndex(cfg);
-    expect(idx.allQualified.size).toBe(1);
-    expect(idx.allQualified.has('ok.y')).toBe(true);
-  });
-});
-
-// ═══ Ref resolution ═══
-
-describe('resolveTaskRef', () => {
-  const cfg: RawPipelineConfig = {
-    name: 'T',
-    tracks: [
-      {
-        id: 'alpha',
-        name: 'A',
-        tasks: [
-          { id: 'plan', prompt: 'p' },
-          { id: 'review', prompt: 'p' },
-        ],
-      },
-      {
-        id: 'beta',
-        name: 'B',
-        tasks: [
-          { id: 'review', prompt: 'p' },
-          { id: 'ship', prompt: 'p' },
-        ],
-      },
-    ],
-  };
-  const idx = buildTaskIndex(cfg);
-
-  test('fully qualified ref resolves when it exists', () => {
-    expect(resolveTaskRef('alpha.plan', 'beta', idx)).toEqual({
-      kind: 'resolved',
-      qid: 'alpha.plan',
-    });
-  });
-
-  test('fully qualified ref that does not exist is not_found', () => {
-    expect(resolveTaskRef('alpha.ghost', 'beta', idx)).toEqual({
-      kind: 'not_found',
-      ref: 'alpha.ghost',
-    });
-  });
-
-  test('bare ref prefers same-track shorthand', () => {
-    // "review" exists in both tracks — from beta's perspective, the same-
-    // track shadow must win over the cross-track ambiguous pool.
-    expect(resolveTaskRef('review', 'beta', idx)).toEqual({
-      kind: 'resolved',
-      qid: 'beta.review',
-    });
-    expect(resolveTaskRef('review', 'alpha', idx)).toEqual({
-      kind: 'resolved',
-      qid: 'alpha.review',
-    });
-  });
-
-  test('bare ref not in current track is ambiguous when multiple tracks have it', () => {
-    const twoForeign: RawPipelineConfig = {
-      name: 'T',
-      tracks: [
-        { id: 'a', name: 'A', tasks: [{ id: 'review', prompt: 'p' }] },
-        { id: 'b', name: 'B', tasks: [{ id: 'review', prompt: 'p' }] },
-        { id: 'c', name: 'C', tasks: [{ id: 'other', prompt: 'p' }] },
-      ],
-    };
-    const idx2 = buildTaskIndex(twoForeign);
-    expect(resolveTaskRef('review', 'c', idx2)).toEqual({ kind: 'ambiguous', ref: 'review' });
-  });
-
-  test('bare ref unique in the pool resolves cross-track', () => {
-    expect(resolveTaskRef('ship', 'alpha', idx)).toEqual({
-      kind: 'resolved',
-      qid: 'beta.ship',
-    });
-  });
-
-  test('bare ref nobody has is not_found', () => {
-    expect(resolveTaskRef('nowhere', 'alpha', idx)).toEqual({
-      kind: 'not_found',
-      ref: 'nowhere',
-    });
-  });
-});
-
-// ═══ Regression: bug #2 — same bare task id in multiple tracks ═══
-
-describe('regression: continue_from across same-named tasks (bug #2)', () => {
-  test('bare continue_from resolves via same-track shadow — qualified id handed downstream', () => {
-    // Two tracks, each with a "review" task and a follower that continues
-    // from it. The follower MUST bind to its own track's review via the
-    // same-track shorthand, not to the other track's review.
-    const resolved: PipelineConfig = {
-      name: 'Same-Bare',
-      tracks: [
-        {
-          id: 'alpha',
-          name: 'Alpha',
-          tasks: [
-            { id: 'review', name: 'Review', prompt: 'do A' },
-            {
-              id: 'ship',
-              name: 'Ship',
-              prompt: 'ship A',
-              depends_on: ['review'],
-              continue_from: 'review',
-            },
-          ],
-        },
-        {
-          id: 'beta',
-          name: 'Beta',
-          tasks: [
-            { id: 'review', name: 'Review', prompt: 'do B' },
-            {
-              id: 'ship',
-              name: 'Ship',
-              prompt: 'ship B',
-              depends_on: ['review'],
-              continue_from: 'review',
-            },
-          ],
-        },
-      ],
-    };
-    const dag = buildDag(resolved);
-    const alphaShip = dag.nodes.get('alpha.ship')!;
-    const betaShip = dag.nodes.get('beta.ship')!;
-    expect(alphaShip.resolvedContinueFrom).toBe('alpha.review');
-    expect(betaShip.resolvedContinueFrom).toBe('beta.review');
-    // And the dep edges get qualified too, preventing engine map-key misses.
-    expect(alphaShip.dependsOn).toContain('alpha.review');
-    expect(betaShip.dependsOn).toContain('beta.review');
-  });
-
-  test('bare continue_from pointing at a foreign ambiguous task throws', () => {
-    const resolved: PipelineConfig = {
-      name: 'Ambiguous',
-      tracks: [
-        {
-          id: 'alpha',
-          name: 'Alpha',
-          tasks: [
-            { id: 'review', name: 'Review', prompt: 'p' },
-            // ship has no local "review" so bare "review" is ambiguous.
-            { id: 'filler', name: 'Filler', prompt: 'p' },
-          ],
-        },
-        {
-          id: 'beta',
-          name: 'Beta',
-          tasks: [{ id: 'review', name: 'Review', prompt: 'p' }],
-        },
-        {
-          id: 'gamma',
-          name: 'Gamma',
-          tasks: [
-            {
-              id: 'ship',
-              name: 'Ship',
-              prompt: 'ship',
-              continue_from: 'review',
-            },
-          ],
-        },
-      ],
-    };
-    expect(() => buildDag(resolved)).toThrow(/ambiguous/i);
-  });
-
-  test('qualified continue_from always wins — no same-track-shadow risk', () => {
-    const resolved: PipelineConfig = {
-      name: 'Qualified',
-      tracks: [
-        {
-          id: 'alpha',
-          name: 'Alpha',
-          tasks: [
-            { id: 'plan', name: 'Plan', prompt: 'p' },
-            {
-              id: 'plan_v2',
-              name: 'Plan v2',
-              prompt: 'p2',
-              continue_from: 'plan',
-            },
-          ],
-        },
-        {
-          id: 'beta',
-          name: 'Beta',
-          tasks: [
-            { id: 'plan', name: 'Plan B', prompt: 'p' },
-            {
-              id: 'cross',
-              name: 'Cross',
-              prompt: 'x',
-              continue_from: 'alpha.plan',
-            },
-          ],
-        },
-      ],
-    };
-    const dag = buildDag(resolved);
-    expect(dag.nodes.get('alpha.plan_v2')!.resolvedContinueFrom).toBe('alpha.plan');
-    expect(dag.nodes.get('beta.cross')!.resolvedContinueFrom).toBe('alpha.plan');
-  });
-});
-
-// ═══ Regression: bug #10 — editor-generated ids always pass validate-raw ═══
-
-describe('regression: TASK_ID_RE is the single source of truth (bug #10)', () => {
-  test('validateRaw rejects exactly what isValidTaskId rejects', () => {
-    // Any string the helper says is invalid must be flagged by validateRaw
-    // as an "invalid characters" error — proving they read from the same
-    // regex rather than two drifted copies.
-    const invalids = ['1bad', 'has.dot', 'with space', '-leading', 'q?mark', ''];
-    for (const badId of invalids) {
-      const cfg: RawPipelineConfig = {
-        name: 'T',
-        tracks: [
-          {
-            id: 'ok',
-            name: 'OK',
-            tasks: [{ id: badId, prompt: 'p' }],
-          },
-        ],
-      };
-      const errs = validateRaw(cfg);
-      expect(errs.length).toBeGreaterThan(0);
-      expect(isValidTaskId(badId)).toBe(false);
-    }
-  });
-});
-
-// ═══ Regression: buildDag topo sort is deterministic (bug #13) ═══
-
-describe('regression: buildDag topo sort is deterministic', () => {
-  const base = (trackOrder: readonly string[]): PipelineConfig => ({
-    name: 'Determinism',
-    tracks: trackOrder.map((id) => ({
-      id,
-      name: id,
-      tasks: [
-        { id: 'a', name: 'A', prompt: 'p' },
-        { id: 'b', name: 'B', prompt: 'p', depends_on: ['a'] },
-      ],
-    })),
-  });
-
-  test('parallel tasks with equal depth sort by qid, independent of YAML order', () => {
-    const forward = buildDag(base(['alpha', 'beta', 'gamma']));
-    const reversed = buildDag(base(['gamma', 'beta', 'alpha']));
-    expect(forward.sorted).toEqual(reversed.sorted);
-    // And the actual order is alphabetical by qid — every "a" before every "b".
-    expect(forward.sorted).toEqual([
-      'alpha.a',
-      'beta.a',
-      'gamma.a',
-      'alpha.b',
-      'beta.b',
-      'gamma.b',
-    ]);
-  });
-
-  test('diamond dependency still produces a unique sorted order', () => {
-    // root -> left, right -> join
-    const cfg: PipelineConfig = {
-      name: 'Diamond',
-      tracks: [
-        {
-          id: 't',
-          name: 't',
-          tasks: [
-            { id: 'root', name: 'r', prompt: 'p' },
-            { id: 'left', name: 'l', prompt: 'p', depends_on: ['root'] },
-            { id: 'right', name: 'r', prompt: 'p', depends_on: ['root'] },
-            { id: 'join', name: 'j', prompt: 'p', depends_on: ['left', 'right'] },
-          ],
-        },
-      ],
-    };
-    const first = buildDag(cfg).sorted;
-    const second = buildDag(cfg).sorted;
-    expect(first).toEqual(second);
-    // root first, join last; left/right in alphabetical order between.
-    expect(first[0]).toBe('t.root');
-    expect(first[first.length - 1]).toBe('t.join');
-    expect(first.indexOf('t.left')).toBeLessThan(first.indexOf('t.right'));
-  });
-});
-
-// ═══ Regression: buildRawDag stays lenient (editor real-time view) ═══
-
-describe('buildRawDag tolerates unresolved refs', () => {
-  test('ambiguous bare continue_from is silently skipped (no edge, no throw)', () => {
-    const cfg: RawPipelineConfig = {
-      name: 'T',
-      tracks: [
-        { id: 'a', name: 'A', tasks: [{ id: 'review', prompt: 'p' }] },
-        { id: 'b', name: 'B', tasks: [{ id: 'review', prompt: 'p' }] },
-        {
-          id: 'c',
-          name: 'C',
-          tasks: [{ id: 'use', prompt: 'p', continue_from: 'review' }],
-        },
-      ],
-    };
-    const raw = buildRawDag(cfg);
-    expect(raw.nodes.size).toBe(3);
-    // No edge for the ambiguous ref — the editor panel should prompt the
-    // user to qualify it instead of silently linking to the wrong track.
-    expect(raw.edges.find((e) => e.to === 'c.use')).toBeUndefined();
-  });
-});

package/src/task-ref.ts

@@ -1,121 +0,0 @@
-// ═══ Task reference resolution — single source of truth ═══
-//
-// Before this module existed, four sites each carried their own copy of the
-// "what is a valid id" + "how do I resolve a bare / same-track-shorthand /
-// fully qualified ref" logic:
-//
-//   - dag.ts/buildDag         (threw on unresolved, threw on ambiguous)
-//   - dag.ts/buildRawDag      (silently skipped unresolved and ambiguous)
-//   - validate-raw.ts         (reported both as errors, with different wording)
-//   - engine.ts/resolveRefInDag  (returned null on ambiguous)
-//
-// In addition, the editor shipped its own regex for id validation in
-// `shared/config-id.ts` and a test-local copy in `config-id-generation.test.ts`,
-// creating multiple places where the character set could drift from the
-// validator. Bugs observed downstream (silent context loss when two tracks
-// happened to share a bare task name; editor-generated ids occasionally
-// failing SDK validate-raw) all traced back to this duplication.
-//
-// Callers now build a TaskIndex once and use `resolveTaskRef` to classify
-// each reference, then decide themselves whether to throw / warn / skip —
-// instead of re-implementing the index build and the lookup logic.
-
-import type { PipelineConfig, RawPipelineConfig } from './types';
-
-/**
- * D8: task and track ids must match this pattern. No dots: the `.` is the
- * qualified-id separator ("trackId.taskId"), so allowing it inside either
- * part would make qid parsing ambiguous and break every resolver below.
- */
-export const TASK_ID_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-
-export function isValidTaskId(id: unknown): id is string {
-  return typeof id === 'string' && TASK_ID_RE.test(id);
-}
-
-/** Canonical qualified form used throughout the engine. */
-export function qualifyTaskId(trackId: string, taskId: string): string {
-  return `${trackId}.${taskId}`;
-}
-
-/** Does the reference already include a track prefix? */
-export function isQualifiedRef(ref: string): boolean {
-  return ref.includes('.');
-}
-
-/**
- * Sentinel stored in `TaskIndex.bareToQualified` when a bare task id is
- * shared by more than one track, making it unresolvable without a prefix.
- * Exposed so callers that want to inspect the index directly know what to
- * look for — but prefer `resolveTaskRef` which returns a typed `kind`.
- */
-export const AMBIGUOUS = '__ambiguous__';
-
-export interface TaskIndex {
-  /** All fully-qualified ids ("trackId.taskId") present in the config. */
-  readonly allQualified: ReadonlySet<string>;
-  /** bare taskId → qid, or the {@link AMBIGUOUS} sentinel. */
-  readonly bareToQualified: ReadonlyMap<string, string>;
-}
-
-/**
- * Build the index used by {@link resolveTaskRef}. Tolerant of partially
- * malformed configs: tracks or tasks missing an `id` are skipped so the
- * editor can call this during real-time validation on in-progress edits.
- */
-export function buildTaskIndex(config: RawPipelineConfig | PipelineConfig): TaskIndex {
-  const allQualified = new Set<string>();
-  const bareToQualified = new Map<string, string>();
-  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);
-      allQualified.add(qid);
-      if (bareToQualified.has(task.id)) {
-        bareToQualified.set(task.id, AMBIGUOUS);
-      } else {
-        bareToQualified.set(task.id, qid);
-      }
-    }
-  }
-  return { allQualified, bareToQualified };
-}
-
-export type RefResolution =
-  | { readonly kind: 'resolved'; readonly qid: string }
-  | { readonly kind: 'ambiguous'; readonly ref: string }
-  | { readonly kind: 'not_found'; readonly ref: string };
-
-/**
- * Resolve a dependency / continue_from reference to a canonical qid.
- *
- *  1. If the ref already contains a `.`, treat it as fully qualified —
- *     return `resolved` when the qid exists, `not_found` otherwise.
- *  2. Otherwise, prefer the same-track shorthand (`fromTrackId.ref`).
- *  3. Fall back to a global bare lookup. Returns `ambiguous` when more
- *     than one track has a task with that bare name.
- *
- * Callers decide the policy: `buildDag` throws on non-resolved, `buildRawDag`
- * skips silently, `validateRaw` emits a structured ValidationError.
- */
-export function resolveTaskRef(
-  ref: string,
-  fromTrackId: string,
-  index: TaskIndex,
-): RefResolution {
-  if (isQualifiedRef(ref)) {
-    return index.allQualified.has(ref)
-      ? { kind: 'resolved', qid: ref }
-      : { kind: 'not_found', ref };
-  }
-  const sameTrack = qualifyTaskId(fromTrackId, ref);
-  if (index.allQualified.has(sameTrack)) {
-    return { kind: 'resolved', qid: sameTrack };
-  }
-  const global = index.bareToQualified.get(ref);
-  if (global === AMBIGUOUS) return { kind: 'ambiguous', ref };
-  if (global !== undefined) return { kind: 'resolved', qid: global };
-  return { kind: 'not_found', ref };
-}

package/src/triggers/file.test.ts

@@ -1,79 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { InMemoryApprovalGateway } from '../approval';
-import { FileTrigger } from './file';
-import type { TagmaRuntime } from '../runtime';
-
-function makeDir(prefix: string): string {
-  return mkdtempSync(join(tmpdir(), prefix));
-}
-
-describe('FileTrigger runtime boundary', () => {
-  test('uses ctx.runtime watch APIs instead of direct chokidar or Bun file APIs', async () => {
-    const dir = makeDir('tagma-file-trigger-runtime-');
-    const calls: string[] = [];
-    const runtime = {
-      async runCommand() {
-        throw new Error('runCommand should not be called by FileTrigger');
-      },
-      async runSpawn() {
-        throw new Error('runSpawn should not be called by FileTrigger');
-      },
-      async ensureDir(path: string) {
-        calls.push(`ensure:${path}`);
-      },
-      async fileExists(path: string) {
-        calls.push(`exists:${path}`);
-        return false;
-      },
-      async *watch(path: string, options?: { cwd?: string }) {
-        calls.push(`watch:${path}:${options?.cwd ?? ''}`);
-        yield { type: 'ready', path: '' };
-        yield { type: 'add', path: 'target.txt' };
-      },
-      now() {
-        return new Date('2026-04-26T00:00:00.000Z');
-      },
-      sleep() {
-        return Promise.resolve();
-      },
-      logStore: {
-        openRunLog() {
-          throw new Error('logStore should not be called by FileTrigger');
-        },
-        taskOutputPath() {
-          throw new Error('logStore should not be called by FileTrigger');
-        },
-        logsDir() {
-          throw new Error('logStore should not be called by FileTrigger');
-        },
-      },
-    } as unknown as TagmaRuntime;
-
-    try {
-      await expect(
-        FileTrigger.watch(
-          { type: 'file', path: 'target.txt', timeout: '0.05s' },
-          {
-            taskId: 't.wait',
-            trackId: 't',
-            workDir: dir,
-            signal: new AbortController().signal,
-            approvalGateway: new InMemoryApprovalGateway(),
-            runtime,
-          } as never,
-        ),
-      ).resolves.toEqual({ path: resolve(dir, 'target.txt') });
-
-      expect(calls).toEqual([
-        `ensure:${dir}`,
-        `watch:${dir}:${dir}`,
-        `exists:${resolve(dir, 'target.txt')}`,
-      ]);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});