@tagma/sdk 0.7.3 → 0.7.5

package/src/hooks.ts

@@ -1,193 +0,0 @@
-import type { HooksConfig, HookCommand, AbortReason } from './types';
-import { shellArgs } from './utils';
-
-type HookEvent =
-  | 'pipeline_start'
-  | 'task_start'
-  | 'task_success'
-  | 'task_failure'
-  | 'pipeline_complete'
-  | 'pipeline_error';
-
-const GATE_HOOKS: ReadonlySet<HookEvent> = new Set(['pipeline_start', 'task_start']);
-
-export interface HookResult {
-  readonly allowed: boolean; // for gate hooks: true = proceed, false = block
-  readonly exitCode: number;
-}
-
-function normalizeCommands(cmd: HookCommand | undefined): readonly string[] {
-  if (!cmd) return [];
-  if (typeof cmd === 'string') return [cmd];
-  return cmd;
-}
-
-const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
-
-async function runSingleHook(
-  command: string,
-  context: unknown,
-  cwd?: string,
-  signal?: AbortSignal,
-  timeoutMs: number = DEFAULT_HOOK_TIMEOUT_MS,
-): Promise<number> {
-  const jsonInput = JSON.stringify(context, null, 2);
-
-  const controller = new AbortController();
-  const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : null;
-
-  // Wire pipeline abort signal into hook process
-  const onAbort = () => controller.abort();
-  if (signal) {
-    if (signal.aborted) {
-      controller.abort();
-    } else {
-      signal.addEventListener('abort', onAbort, { once: true });
-    }
-  }
-
-  try {
-    const proc = Bun.spawn(shellArgs(command) as string[], {
-      stdin: 'pipe',
-      stdout: 'pipe',
-      stderr: 'pipe',
-      signal: controller.signal,
-      ...(cwd ? { cwd } : {}),
-    });
-
-    if (proc.stdin) {
-      try {
-        proc.stdin.write(jsonInput);
-        proc.stdin.end();
-      } catch {
-        // Process may exit before reading stdin (e.g. `exit 1`), ignore EPIPE
-      }
-    }
-
-    // Consume stdout and stderr concurrently with waiting for exit.
-    // Sequential reads after proc.exited risk a pipe-buffer deadlock when
-    // hook output exceeds the ~64 KB kernel buffer.
-    const [exitCode, stdout, stderr] = await Promise.all([
-      proc.exited,
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-
-    if (stdout.trim()) {
-      console.warn(`[hook: ${command}] stdout: ${stdout.trim()}`);
-    }
-    if (stderr.trim()) {
-      console.error(`[hook: ${command}] stderr: ${stderr.trim()}`);
-    }
-
-    return exitCode;
-  } catch (err) {
-    console.error(
-      `[hook: ${command}] spawn error: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    return -1;
-  } finally {
-    if (timer) clearTimeout(timer);
-    if (signal) signal.removeEventListener('abort', onAbort);
-  }
-}
-
-export async function executeHook(
-  hooks: HooksConfig | undefined,
-  event: HookEvent,
-  context: unknown,
-  workDir?: string,
-  signal?: AbortSignal,
-): Promise<HookResult> {
-  if (!hooks) return { allowed: true, exitCode: 0 };
-
-  const commands = normalizeCommands(hooks[event]);
-  if (commands.length === 0) return { allowed: true, exitCode: 0 };
-
-  const isGate = GATE_HOOKS.has(event);
-
-  for (const cmd of commands) {
-    const exitCode = await runSingleHook(cmd, context, workDir, signal);
-
-    if (isGate && exitCode === 1) {
-      // Only exit code 1 has gate semantics (block execution)
-      return { allowed: false, exitCode };
-    }
-
-    if (exitCode !== 0) {
-      // Non-zero but not 1: hook itself had an error, log but don't block
-      console.warn(`[hook: ${event}] "${cmd}" exited with code ${exitCode}`);
-    }
-  }
-
-  return { allowed: true, exitCode: 0 };
-}
-
-// ═══ Context Builders ═══
-
-export interface PipelineInfo {
-  readonly name: string;
-  readonly run_id: string;
-  readonly started_at: string;
-  readonly finished_at?: string;
-  readonly duration_ms?: number;
-}
-
-export interface TrackInfo {
-  readonly id: string;
-  readonly name: string;
-}
-
-export interface TaskInfo {
-  readonly id: string;
-  readonly name: string;
-  readonly type: 'ai' | 'command';
-  readonly status: string;
-  readonly exit_code: number | null;
-  readonly duration_ms: number | null;
-  readonly stderr_path: string | null;
-  readonly session_id: string | null;
-  readonly started_at: string | null;
-  readonly finished_at: string | null;
-}
-
-export function buildPipelineStartContext(pipeline: PipelineInfo) {
-  return { event: 'pipeline_start', pipeline };
-}
-
-export function buildTaskContext(
-  event: 'task_start' | 'task_success' | 'task_failure',
-  pipeline: PipelineInfo,
-  track: TrackInfo,
-  task: TaskInfo,
-) {
-  return { event, pipeline, track, task };
-}
-
-export function buildPipelineCompleteContext(
-  pipeline: PipelineInfo & { finished_at: string; duration_ms: number },
-  summary: {
-    total: number;
-    success: number;
-    failed: number;
-    skipped: number;
-    timeout: number;
-    blocked: number;
-  },
-) {
-  return { event: 'pipeline_complete', pipeline, summary };
-}
-
-export function buildPipelineErrorContext(
-  pipeline: PipelineInfo,
-  error: string,
-  eventType?: string,
-  abortReason?: AbortReason,
-) {
-  return {
-    event: eventType ?? 'pipeline_error',
-    pipeline,
-    error,
-    ...(abortReason !== undefined ? { abort_reason: abortReason } : {}),
-  };
-}

package/src/index.ts

@@ -1,33 +0,0 @@
-export { createTagma } from './tagma';
-export type { CreateTagmaOptions, Tagma, TagmaRunOptions } from './tagma';
-export { bunRuntime } from './runtime';
-export type { TagmaRuntime, RunOptions as RuntimeRunOptions } from './runtime';
-export { definePipeline } from './pipeline-definition';
-export { PluginRegistry } from './registry';
-export { TriggerBlockedError, TriggerTimeoutError } from './engine';
-export type { EngineResult, RunEventPayload } from './engine';
-export { RUN_PROTOCOL_VERSION, TASK_LOG_CAP } from './types';
-export type {
-  PipelineConfig,
-  RawPipelineConfig,
-  RawTrackConfig,
-  RawTaskConfig,
-  TrackConfig,
-  TaskConfig,
-  RunSnapshotPayload,
-  WireRunEvent,
-  RunTaskState,
-  TaskLogLine,
-  ApprovalRequestInfo,
-  TaskStatus,
-  ApprovalRequest,
-  PluginCategory,
-  PluginCapabilities,
-  PluginSetupContext,
-  TagmaPlugin,
-  DriverPlugin,
-  TriggerPlugin,
-  CompletionPlugin,
-  MiddlewarePlugin,
-  RunEventPayload as PipelineRunEventPayload,
-} from '@tagma/types';

package/src/logger.ts

@@ -1,182 +0,0 @@
-import { resolve, dirname } from 'node:path';
-import { mkdirSync, writeFileSync, openSync, writeSync, closeSync } from 'node:fs';
-
-/**
- * Structured record emitted for every log line. Consumers (e.g. the editor
- * server) use this to stream process-level detail into UIs alongside the
- * on-disk pipeline.log. `taskId` is extracted from a `[task:<id>]` prefix
- * when the call site passes one, or overridden explicitly via the optional
- * `taskId` argument on `section`/`quiet` (which carry no prefix).
- */
-export type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet';
-
-export interface LogRecord {
-  readonly level: LogLevel;
-  readonly taskId: string | null;
-  readonly timestamp: string;
-  readonly text: string;
-}
-
-export type LogListener = (record: LogRecord) => void;
-
-const TASK_PREFIX_RE = /\[task:([^\]]+)\]/;
-
-function taskIdFromPrefix(prefix: string): string | null {
-  const m = TASK_PREFIX_RE.exec(prefix);
-  return m ? m[1] : null;
-}
-
-/**
- * Dual-channel logger.
- *
- *   - `info/warn/error` → console AND file (brief, user-visible events)
- *   - `debug`           → file ONLY (verbose diagnostics)
- *   - `section`         → file ONLY (visual separators)
- *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
- *
- * Log file path: <workDir>/.tagma/logs/<runId>/pipeline.log (one file per pipeline run,
- * truncated on construction). Every line is also forwarded to the optional
- * `onLine` callback as a structured `LogRecord`, so callers that want to
- * stream the run process over IPC/SSE don't need to tail the file.
- */
-export class Logger {
-  private readonly filePath: string;
-  private readonly runDir: string;
-  private readonly onLine: LogListener | null;
-  /** Persistent file descriptor for append writes (avoids open/close per line). */
-  private fd: number | null;
-
-  constructor(workDir: string, runId: string, onLine?: LogListener) {
-    this.runDir = resolve(workDir, '.tagma', 'logs', runId);
-    this.filePath = resolve(this.runDir, 'pipeline.log');
-    this.onLine = onLine ?? null;
-    mkdirSync(dirname(this.filePath), { recursive: true });
-    const header =
-      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
-      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
-      `# Work dir: ${workDir}\n\n`;
-    writeFileSync(this.filePath, header);
-    // Open once for all subsequent appends (O_APPEND is implied by 'a' flag)
-    this.fd = openSync(this.filePath, 'a');
-  }
-
-  info(prefix: string, message: string): void {
-    const ts = timestamp();
-    const line = `${ts} ${prefix} ${message}`;
-    // eslint-disable-next-line no-console
-    console.log(line);
-    this.emit('info', ts, line, taskIdFromPrefix(prefix));
-    this.append(line);
-  }
-
-  warn(prefix: string, message: string): void {
-    const ts = timestamp();
-    const line = `${ts} ${prefix} WARN: ${message}`;
-    console.warn(line);
-    this.emit('warn', ts, line, taskIdFromPrefix(prefix));
-    this.append(line);
-  }
-
-  error(prefix: string, message: string): void {
-    const ts = timestamp();
-    const line = `${ts} ${prefix} ERROR: ${message}`;
-    console.error(line);
-    this.emit('error', ts, line, taskIdFromPrefix(prefix));
-    this.append(line);
-  }
-
-  /** File-only diagnostic log line. */
-  debug(prefix: string, message: string): void {
-    const ts = timestamp();
-    const line = `${ts} ${prefix} DEBUG: ${message}`;
-    this.emit('debug', ts, line, taskIdFromPrefix(prefix));
-    this.append(line);
-  }
-
-  /** File-only visual separator with title. */
-  section(title: string, taskId?: string | null): void {
-    const ts = timestamp();
-    const text = `\n━━━ ${title} ━━━`;
-    this.emit('section', ts, text, taskId ?? null);
-    this.append(text);
-  }
-
-  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
-  quiet(message: string, taskId?: string | null): void {
-    const ts = timestamp();
-    this.emit('quiet', ts, message, taskId ?? null);
-    this.append(message);
-  }
-
-  private append(line: string): void {
-    if (this.fd === null) return;
-    try {
-      const data = line.endsWith('\n') ? line : line + '\n';
-      writeSync(this.fd, data);
-    } catch {
-      // Swallow log write failures; engine correctness shouldn't depend on logging.
-    }
-  }
-
-  /** Close the persistent file handle. Called by the engine at run completion. */
-  close(): void {
-    if (this.fd !== null) {
-      try {
-        closeSync(this.fd);
-      } catch {
-        /* already closed */
-      }
-      this.fd = null;
-    }
-  }
-
-  private emit(level: LogLevel, ts: string, text: string, taskId: string | null): void {
-    if (!this.onLine) return;
-    try {
-      this.onLine({ level, taskId, timestamp: ts, text });
-    } catch {
-      // Never let a listener error derail the pipeline.
-    }
-  }
-
-  get path(): string {
-    return this.filePath;
-  }
-
-  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
-  get dir(): string {
-    return this.runDir;
-  }
-}
-
-function timestamp(): string {
-  const d = new Date();
-  const hh = String(d.getHours()).padStart(2, '0');
-  const mm = String(d.getMinutes()).padStart(2, '0');
-  const ss = String(d.getSeconds()).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${hh}:${mm}:${ss}.${ms}`;
-}
-
-/** Return the last `n` non-empty lines of `text`, joined with newlines. */
-export function tailLines(text: string, n: number): string {
-  if (!text) return '';
-  const lines = text.split(/\r?\n/).filter((l) => l.length > 0);
-  return lines.slice(-n).join('\n');
-}
-
-/**
- * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
- * appending a marker when truncation occurred.
- * Uses TextEncoder so CJK and emoji (multi-byte) characters are counted correctly.
- */
-export function clip(text: string, maxBytes = 16 * 1024): string {
-  if (!text) return '';
-  const encoder = new TextEncoder();
-  const bytes = encoder.encode(text);
-  if (bytes.length <= maxBytes) return text;
-  const omittedBytes = bytes.length - maxBytes;
-  // TextDecoder handles partial code-point boundaries safely (replacement char insertion)
-  const truncated = new TextDecoder().decode(bytes.slice(0, maxBytes));
-  return truncated + `\n…[truncated ${omittedBytes} bytes]`;
-}

package/src/middlewares/static-context.ts

@@ -1,49 +0,0 @@
-import { basename } from 'path';
-import type { MiddlewarePlugin, MiddlewareContext, PromptDocument } from '../types';
-import { validatePath } from '../utils';
-import { appendContext } from '../prompt-doc';
-
-export const StaticContextMiddleware: MiddlewarePlugin = {
-  name: 'static_context',
-  schema: {
-    description: 'Prepend a reference file to the prompt as static context.',
-    fields: {
-      file: {
-        type: 'path',
-        required: true,
-        description: 'Path to the reference file (relative to workDir or absolute).',
-        placeholder: 'docs/spec.md',
-      },
-      label: {
-        type: 'string',
-        description: 'Header shown before the content. Defaults to "Reference: <basename>".',
-        placeholder: 'Reference: spec.md',
-      },
-    },
-  },
-
-  async enhanceDoc(
-    doc: PromptDocument,
-    config: Record<string, unknown>,
-    ctx: MiddlewareContext,
-  ): Promise<PromptDocument> {
-    const filePath = config.file as string;
-    if (!filePath) throw new Error('static_context middleware: "file" is required');
-
-    const safePath = validatePath(filePath, ctx.workDir);
-    const file = Bun.file(safePath);
-
-    if (!(await file.exists())) {
-      console.warn(`static_context: file ${filePath} not found, skipping`);
-      return doc;
-    }
-
-    const content = await file.text();
-    const label = (config.label as string) ?? `Reference: ${basename(filePath)}`;
-
-    // Append a labeled context block; the engine's serializer joins blocks
-    // with blank lines and places the task last. No [Task] header here —
-    // that framing is the driver's concern (e.g. opencode's agent_profile).
-    return appendContext(doc, { label, content });
-  },
-};

package/src/pipeline-definition.ts

@@ -1,5 +0,0 @@
-import type { RawPipelineConfig } from './types';
-
-export function definePipeline<T extends RawPipelineConfig>(pipeline: T): T {
-  return pipeline;
-}

package/src/pipeline-runner.test.ts

@@ -1,91 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { bootstrapBuiltins } from './bootstrap';
-import { PipelineRunner } from './pipeline-runner';
-import { PluginRegistry } from './registry';
-import type { PipelineConfig } from './types';
-
-function makeDir(): string {
-  return mkdtempSync(join(tmpdir(), 'tagma-pipeline-runner-'));
-}
-
-function bindingsPipeline(dir: string): PipelineConfig {
-  const emit = join(dir, 'emit.js');
-  writeFileSync(
-    emit,
-    'process.stdout.write(JSON.stringify({ city: "Shanghai" }) + "\\n");\n',
-  );
-  const echo = join(dir, 'echo.js');
-  writeFileSync(echo, 'process.stdout.write(process.argv[2] + "\\n");\n');
-
-  return {
-    name: 'runner-snapshot',
-    tracks: [
-      {
-        id: 't',
-        name: 'T',
-        tasks: [
-          {
-            id: 'up',
-            name: 'up',
-            command: `node "${emit}"`,
-            outputs: { city: { type: 'string' } },
-          },
-          {
-            id: 'down',
-            name: 'down',
-            depends_on: ['up'],
-            command: `node "${echo}" "{{inputs.city}}"`,
-            inputs: { city: { from: 't.up.outputs.city', type: 'string', required: true } },
-          },
-        ],
-      },
-    ],
-  };
-}
-
-async function run(config: PipelineConfig, dir: string): Promise<PipelineRunner> {
-  const registry = new PluginRegistry();
-  bootstrapBuiltins(registry);
-  const runner = new PipelineRunner(config, dir, {
-    registry,
-    skipPluginLoading: true,
-  });
-
-  const result = await runner.start();
-  expect(result.success).toBe(true);
-  return runner;
-}
-
-describe('PipelineRunner task snapshot', () => {
-  test('getTasks reflects task_update inputs and outputs', async () => {
-    const dir = makeDir();
-    try {
-      const runner = await run(bindingsPipeline(dir), dir);
-
-      const tasks = runner.getTasks();
-      const up = tasks.get('t.up');
-      const down = tasks.get('t.down');
-      expect(up?.outputs).toEqual({ city: 'Shanghai' });
-      expect(down?.inputs).toEqual({ city: 'Shanghai' });
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  test('getTasks folds streamed task logs into the task snapshot', async () => {
-    const dir = makeDir();
-    try {
-      const runner = await run(bindingsPipeline(dir), dir);
-
-      const tasks = runner.getTasks();
-      const up = tasks.get('t.up');
-      expect(up?.logs.length).toBeGreaterThan(0);
-      expect(up?.totalLogCount).toBeGreaterThan(0);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-});