@tagma/sdk 0.1.2

package/src/hooks.ts

@@ -0,0 +1,138 @@
+import type { HooksConfig, HookCommand } 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;
+}
+
+async function runSingleHook(command: string, context: unknown, cwd?: string): Promise<number> {
+  const jsonInput = JSON.stringify(context, null, 2);
+
+  const proc = Bun.spawn(shellArgs(command) as string[], {
+    stdin: 'pipe',
+    stdout: 'pipe',
+    stderr: 'pipe',
+    ...(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
+    }
+  }
+
+  const exitCode = await proc.exited;
+  const stderr = await new Response(proc.stderr).text();
+
+  if (stderr.trim()) {
+    console.error(`[hook: ${command}] stderr: ${stderr.trim()}`);
+  }
+
+  return exitCode;
+}
+
+export async function executeHook(
+  hooks: HooksConfig | undefined,
+  event: HookEvent,
+  context: unknown,
+  workDir?: string,
+): 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);
+
+    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 output_path: string | 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,
+) {
+  return { event: eventType ?? 'pipeline_error', pipeline, error };
+}

package/src/logger.ts

@@ -0,0 +1,100 @@
+import { resolve, dirname } from 'node:path';
+import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * 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>/tmp/pipeline.log (one file per pipeline run,
+ * truncated on construction).
+ */
+export class Logger {
+  private readonly filePath: string;
+
+  constructor(workDir: string, runId: string) {
+    this.filePath = resolve(workDir, 'tmp', 'pipeline.log');
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(
+      this.filePath,
+      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
+      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
+      `# Work dir: ${workDir}\n\n`,
+    );
+  }
+
+  info(prefix: string, message: string): void {
+    const line = `${timestamp()} ${prefix} ${message}`;
+    console.log(line);
+    this.append(line);
+  }
+
+  warn(prefix: string, message: string): void {
+    const line = `${timestamp()} ${prefix} WARN: ${message}`;
+    console.warn(line);
+    this.append(line);
+  }
+
+  error(prefix: string, message: string): void {
+    const line = `${timestamp()} ${prefix} ERROR: ${message}`;
+    console.error(line);
+    this.append(line);
+  }
+
+  /** File-only diagnostic log line. */
+  debug(prefix: string, message: string): void {
+    this.append(`${timestamp()} ${prefix} DEBUG: ${message}`);
+  }
+
+  /** File-only visual separator with title. */
+  section(title: string): void {
+    this.append(`\n━━━ ${title} ━━━`);
+  }
+
+  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
+  quiet(message: string): void {
+    this.append(message);
+  }
+
+  private append(line: string): void {
+    try {
+      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
+    } catch {
+      // Swallow log write failures; engine correctness shouldn't depend on logging.
+    }
+  }
+
+  get path(): string {
+    return this.filePath;
+  }
+}
+
+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.
+ */
+export function clip(text: string, maxBytes = 16 * 1024): string {
+  if (!text) return '';
+  if (text.length <= maxBytes) return text;
+  const omitted = text.length - maxBytes;
+  return text.slice(0, maxBytes) + `\n…[truncated ${omitted} chars]`;
+}

package/src/middlewares/static-context.ts

@@ -0,0 +1,29 @@
+import { basename } from 'path';
+import type { MiddlewarePlugin, MiddlewareContext } from '../types';
+import { validatePath } from '../utils';
+
+export const StaticContextMiddleware: MiddlewarePlugin = {
+  name: 'static_context',
+
+  async enhance(
+    prompt: string,
+    config: Record<string, unknown>,
+    ctx: MiddlewareContext,
+  ): Promise<string> {
+    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 prompt;
+    }
+
+    const content = await file.text();
+    const label = (config.label as string) ?? `Reference: ${basename(filePath)}`;
+
+    return `[${label}]\n${content}\n\n[Task]\n${prompt}`;
+  },
+};

package/src/registry.ts

@@ -0,0 +1,56 @@
+import type {
+  PluginCategory, DriverPlugin, TriggerPlugin,
+  CompletionPlugin, MiddlewarePlugin,
+} from './types';
+
+type PluginType = DriverPlugin | TriggerPlugin | CompletionPlugin | MiddlewarePlugin;
+
+const registries = {
+  drivers:     new Map<string, DriverPlugin>(),
+  triggers:    new Map<string, TriggerPlugin>(),
+  completions: new Map<string, CompletionPlugin>(),
+  middlewares: new Map<string, MiddlewarePlugin>(),
+};
+
+export function registerPlugin<T extends PluginType>(
+  category: PluginCategory, type: string, handler: T,
+): void {
+  const registry = registries[category] as Map<string, T>;
+  if (registry.has(type)) {
+    throw new Error(`${category} type "${type}" is already registered`);
+  }
+  registry.set(type, handler);
+}
+
+export function getHandler<T extends PluginType>(
+  category: PluginCategory, type: string,
+): T {
+  const handler = registries[category].get(type);
+  if (!handler) {
+    throw new Error(
+      `${category} type "${type}" not registered.\n` +
+      `Install the plugin: bun add @tagma/${category.replace(/s$/, '')}-${type}`
+    );
+  }
+  return handler as T;
+}
+
+export function hasHandler(category: PluginCategory, type: string): boolean {
+  return registries[category].has(type);
+}
+
+export async function loadPlugins(pluginNames: readonly string[]): Promise<void> {
+  for (const name of pluginNames) {
+    const mod = await import(name);
+    if (!mod.pluginCategory || !mod.pluginType || !mod.default) {
+      throw new Error(
+        `Plugin "${name}" must export pluginCategory, pluginType, and default`
+      );
+    }
+    registerPlugin(mod.pluginCategory, mod.pluginType, mod.default);
+  }
+}
+
+export function listRegistered(category: PluginCategory): string[] {
+  return [...registries[category].keys()];
+}

package/src/runner.ts

@@ -0,0 +1,194 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import type { SpawnSpec, DriverPlugin, TaskResult, TaskConfig } from './types';
+import { shellArgs } from './utils';
+
+export interface RunOptions {
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal; // pipeline-level abort
+}
+
+/**
+ * On Windows, Bun.spawn does NOT auto-append PATHEXT extensions like
+ * CreateProcess does. A bare command like `claude` fails with ENOENT if the
+ * actual file on disk is `claude.cmd` / `claude.bat` / `claude.ps1`. We
+ * manually resolve the command against PATH + PATHEXT here so Drivers can
+ * keep using short names (`claude`, `npx`, etc.) cross-platform.
+ *
+ * Returns the original name if resolution fails; Bun will raise the same
+ * ENOENT it would have otherwise.
+ */
+function resolveWindowsExe(
+  args: readonly string[],
+  envPath: string,
+): readonly string[] {
+  if (process.platform !== 'win32' || args.length === 0) return args;
+  const cmd = args[0]!;
+  // Already a full path or has an extension → trust caller.
+  if (isAbsolute(cmd) || /\.[a-z0-9]+$/i.test(cmd)) return args;
+
+  const exts = (
+    process.env.PATHEXT ??
+    '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC'
+  )
+    .split(';')
+    .filter(Boolean);
+  const dirs = envPath.split(';').filter(Boolean);
+
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, cmd + ext);
+      if (existsSync(candidate)) {
+        return [candidate, ...args.slice(1)];
+      }
+    }
+  }
+  return args;
+}
+
+/** Build a "failed before spawn" result. */
+function failResult(stderr: string, durationMs: number): TaskResult {
+  return {
+    exitCode: -1,
+    stdout: '',
+    stderr,
+    outputPath: null,
+    stderrPath: null,
+    durationMs,
+    sessionId: null,
+    normalizedOutput: null,
+  };
+}
+
+export async function runSpawn(
+  spec: SpawnSpec,
+  driver: DriverPlugin | null,
+  opts: RunOptions = {},
+): Promise<TaskResult> {
+  const { timeoutMs, signal } = opts;
+  const start = performance.now();
+  const elapsed = () => Math.round(performance.now() - start);
+
+  const mergedEnv = { ...process.env, ...(spec.env ?? {}) };
+  const resolvedArgs = resolveWindowsExe(
+    spec.args,
+    mergedEnv.PATH ?? process.env.PATH ?? '',
+  );
+
+  // ── 1. Spawn (catch ENOENT / bad-cwd up front) ────────────────────────
+  let proc: ReturnType<typeof Bun.spawn>;
+  try {
+    proc = Bun.spawn(resolvedArgs as string[], {
+      cwd: spec.cwd,
+      env: mergedEnv,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: spec.stdin ? 'pipe' : undefined,
+    });
+  } catch (err) {
+    return failResult(String(err), elapsed());
+  }
+
+  // ── 2. Write stdin ─────────────────────────────────────────────────────
+  // Child may exit before reading (e.g. quick-fail commands that don't
+  // touch stdin) → swallow EPIPE rather than surfacing it as an
+  // engine-level error.
+  if (spec.stdin && proc.stdin && typeof proc.stdin !== 'number') {
+    try {
+      proc.stdin.write(spec.stdin);
+      proc.stdin.end();
+    } catch {
+      /* ignore EPIPE / closed-pipe errors */
+    }
+  }
+
+  // ── 3. Timeout & abort handling ────────────────────────────────────────
+  let killedByUs = false;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let forceTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const killGracefully = () => {
+    if (killedByUs) return;
+    killedByUs = true;
+    proc.kill('SIGTERM');
+    // If the child ignores SIGTERM, escalate to SIGKILL after 3 s.
+    forceTimer = setTimeout(() => {
+      try {
+        proc.kill('SIGKILL');
+      } catch {
+        /* already exited */
+      }
+    }, 3_000);
+  };
+
+  if (timeoutMs && timeoutMs > 0) {
+    timer = setTimeout(killGracefully, timeoutMs);
+  }
+
+  const onAbort = () => killGracefully();
+  if (signal) {
+    if (signal.aborted) {
+      killGracefully();
+    } else {
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  }
+
+  // ── 4. Collect output & wait (parallel to avoid pipe-buffer deadlock) ─
+  const stdoutStream = typeof proc.stdout === 'object' ? proc.stdout : undefined;
+  const stderrStream = typeof proc.stderr === 'object' ? proc.stderr : undefined;
+
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    stdoutStream ? new Response(stdoutStream).text() : Promise.resolve(''),
+    stderrStream ? new Response(stderrStream).text() : Promise.resolve(''),
+  ]);
+
+  // ── 5. Cleanup timers & listeners ──────────────────────────────────────
+  if (timer) clearTimeout(timer);
+  if (forceTimer) clearTimeout(forceTimer);
+  if (signal) signal.removeEventListener('abort', onAbort);
+
+  const durationMs = elapsed();
+
+  // If we killed the process but it had already exited with a real code
+  // before our signal landed, don't treat it as a timeout.
+  if (killedByUs && exitCode !== 0) {
+    return {
+      exitCode: -1,
+      stdout,
+      stderr,
+      outputPath: null,
+      stderrPath: null,
+      durationMs,
+      sessionId: null,
+      normalizedOutput: null,
+    };
+  }
+
+  // ── 6. Let driver extract metadata ─────────────────────────────────────
+  const meta = driver?.parseResult?.(stdout, stderr) ?? {};
+
+  return {
+    exitCode,
+    stdout,
+    stderr,
+    outputPath: null,
+    stderrPath: null,
+    durationMs,
+    sessionId: meta.sessionId ?? null,
+    normalizedOutput: meta.normalizedOutput ?? null,
+  };
+}
+
+export async function runCommand(
+  command: string,
+  cwd: string,
+  opts: RunOptions = {},
+): Promise<TaskResult> {
+  const spec: SpawnSpec = {
+    args: shellArgs(command),
+    cwd,
+  };
+  return runSpawn(spec, null, opts);
+}