@tagma/sdk 0.1.2

package/README.md

@@ -0,0 +1 @@
+# tagma-sdk

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@tagma/sdk",
+  "version": "0.1.2",
+  "type": "module",
+  "workspaces": [
+    "plugins/*"
+  ],
+  "main": "./src/sdk.ts",
+  "exports": {
+    ".": "./src/sdk.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "release": "bun scripts/release.ts",
+    "release:publish": "bun scripts/release.ts --publish"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "chokidar": "^4.0.0",
+    "@tagma/types": "0.1.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "bun-types": "latest",
+    "typescript": "^6.0.2",
+    "@tagma/driver-codex": "0.1.2",
+    "@tagma/driver-opencode": "0.1.2"
+  }
+}

package/src/adapters/stdin-approval.ts

@@ -0,0 +1,117 @@
+import * as readline from 'readline';
+import type { ApprovalGateway, ApprovalRequest } from '../approval';
+
+// ═══ CLI Stdin Adapter ═══
+//
+// Subscribes to the gateway's 'requested' events, prompts the user on stdout,
+// reads a line from stdin, and calls gateway.resolve(). Handles at most one
+// prompt at a time — additional requests queue up.
+
+export interface StdinApprovalAdapter {
+  readonly detach: () => void;
+}
+
+export function attachStdinApprovalAdapter(gateway: ApprovalGateway): StdinApprovalAdapter {
+  const queue: ApprovalRequest[] = [];
+  let processing = false;
+  let rl: readline.Interface | null = null;
+
+  function ensureReadline(): readline.Interface {
+    if (!rl) {
+      rl = readline.createInterface({ input: process.stdin, terminal: false });
+    }
+    return rl;
+  }
+
+  function readOneLine(): Promise<string> {
+    return new Promise((resolvePromise) => {
+      const reader = ensureReadline();
+      const handler = (line: string): void => {
+        reader.off('line', handler);
+        resolvePromise(line);
+      };
+      reader.on('line', handler);
+    });
+  }
+
+  async function processNext(): Promise<void> {
+    if (processing) return;
+    processing = true;
+    try {
+      while (queue.length > 0) {
+        const req = queue.shift()!;
+        // If the request was already resolved by another path while queued, skip it.
+        if (!gateway.pending().some((p) => p.id === req.id)) continue;
+
+        const optionsStr = req.options.join(' / ');
+        process.stdout.write(
+          `\n[APPROVAL REQUIRED] ${req.message}\n` +
+            `  id:      ${req.id}\n` +
+            `  task:    ${req.taskId}${req.trackId ? ` (track: ${req.trackId})` : ''}\n` +
+            `  options: ${optionsStr}\n` +
+            `  > `,
+        );
+
+        const input = (await readOneLine()).trim().toLowerCase();
+
+        const approveAliases = new Set(['approve', 'yes', 'y', 'ok', 'true', '1']);
+        const rejectAliases = new Set(['reject', 'no', 'n', 'deny', 'false', '0']);
+        const matchedOption = req.options.find((o) => o.toLowerCase() === input);
+
+        if (matchedOption) {
+          const isReject = rejectAliases.has(matchedOption.toLowerCase());
+          gateway.resolve(req.id, {
+            outcome: isReject ? 'rejected' : 'approved',
+            choice: matchedOption,
+            actor: 'cli',
+          });
+        } else if (approveAliases.has(input)) {
+          gateway.resolve(req.id, { outcome: 'approved', choice: input, actor: 'cli' });
+        } else if (rejectAliases.has(input)) {
+          gateway.resolve(req.id, {
+            outcome: 'rejected',
+            choice: input,
+            actor: 'cli',
+            reason: 'user rejected via CLI',
+          });
+        } else {
+          process.stdout.write(`  unrecognized input "${input}" — treating as rejection\n`);
+          gateway.resolve(req.id, {
+            outcome: 'rejected',
+            actor: 'cli',
+            reason: `unrecognized CLI input: ${input}`,
+          });
+        }
+      }
+    } finally {
+      processing = false;
+    }
+  }
+
+  const unsubscribe = gateway.subscribe((event) => {
+    switch (event.type) {
+      case 'requested':
+        queue.push(event.request);
+        void processNext();
+        return;
+      case 'resolved':
+      case 'expired':
+      case 'aborted': {
+        // Drop from queue if it's still waiting its turn.
+        const idx = queue.findIndex((r) => r.id === event.request.id);
+        if (idx >= 0) queue.splice(idx, 1);
+        return;
+      }
+    }
+  });
+
+  return {
+    detach: () => {
+      unsubscribe();
+      if (rl) {
+        rl.close();
+        rl = null;
+      }
+    },
+  };
+}

package/src/adapters/websocket-approval.ts

@@ -0,0 +1,144 @@
+import type { ApprovalGateway, ApprovalEvent } from '../approval';
+
+// ═══ WebSocket Approval Adapter ═══
+//
+// Bridges the ApprovalGateway to WebSocket clients (e.g. a frontend UI).
+// Mirrors the stdin-approval adapter pattern: subscribe to gateway events,
+// forward them as JSON to all connected clients, and call gateway.resolve()
+// when a client sends a resolution message.
+//
+// Protocol — server → client:
+//   { type: 'pending',             requests: ApprovalRequest[] }   ← sent on connect
+//   { type: 'approval_requested',  request:  ApprovalRequest }
+//   { type: 'approval_resolved',   request:  ApprovalRequest, decision: ApprovalDecision }
+//   { type: 'approval_expired',    request:  ApprovalRequest }
+//   { type: 'approval_aborted',    request:  ApprovalRequest, reason: string }
+//
+// Protocol — client → server:
+//   { type: 'resolve', approvalId: string, outcome: 'approved'|'rejected',
+//     choice?: string, actor?: string, reason?: string }
+
+export interface WebSocketApprovalAdapterOptions {
+  port?: number;      // default: 3000
+  hostname?: string;  // default: 'localhost'
+}
+
+export interface WebSocketApprovalAdapter {
+  readonly port: number;
+  readonly detach: () => void;
+}
+
+export function attachWebSocketApprovalAdapter(
+  gateway: ApprovalGateway,
+  options: WebSocketApprovalAdapterOptions = {},
+): WebSocketApprovalAdapter {
+  const port = options.port ?? 3000;
+  const hostname = options.hostname ?? 'localhost';
+
+  const clients = new Set<import('bun').ServerWebSocket<unknown>>();
+
+  function broadcast(msg: unknown): void {
+    const text = JSON.stringify(msg);
+    for (const ws of clients) {
+      ws.send(text);
+    }
+  }
+
+  const unsubscribe = gateway.subscribe((event: ApprovalEvent) => {
+    switch (event.type) {
+      case 'requested':
+        broadcast({ type: 'approval_requested', request: event.request });
+        break;
+      case 'resolved':
+        broadcast({ type: 'approval_resolved', request: event.request, decision: event.decision });
+        break;
+      case 'expired':
+        broadcast({ type: 'approval_expired', request: event.request });
+        break;
+      case 'aborted':
+        broadcast({ type: 'approval_aborted', request: event.request, reason: event.reason });
+        break;
+    }
+  });
+
+  const server = Bun.serve({
+    port,
+    hostname,
+
+    fetch(req, server) {
+      if (server.upgrade(req)) return undefined;
+      return new Response('tagma-sdk WebSocket approval endpoint', { status: 426 });
+    },
+
+    websocket: {
+      open(ws) {
+        clients.add(ws);
+        // Sync current pending approvals to newly connected client.
+        ws.send(JSON.stringify({ type: 'pending', requests: gateway.pending() }));
+      },
+
+      message(ws, raw) {
+        let msg: unknown;
+        try {
+          msg = JSON.parse(typeof raw === 'string' ? raw : raw.toString());
+        } catch {
+          ws.send(JSON.stringify({ type: 'error', message: 'invalid JSON' }));
+          return;
+        }
+
+        if (!isResolveMessage(msg)) {
+          ws.send(JSON.stringify({ type: 'error', message: 'unknown message type' }));
+          return;
+        }
+
+        const ok = gateway.resolve(msg.approvalId, {
+          outcome: msg.outcome,
+          choice: msg.choice,
+          actor: msg.actor ?? 'websocket',
+          reason: msg.reason,
+        });
+
+        if (!ok) {
+          ws.send(JSON.stringify({
+            type: 'error',
+            message: `approval ${msg.approvalId} not found or already resolved`,
+          }));
+        }
+      },
+
+      close(ws) {
+        clients.delete(ws);
+      },
+    },
+  });
+
+  return {
+    port: server.port,
+    detach() {
+      unsubscribe();
+      clients.clear();
+      server.stop(true);
+    },
+  };
+}
+
+// ── Type guard ──
+
+interface ResolveMessage {
+  type: 'resolve';
+  approvalId: string;
+  outcome: 'approved' | 'rejected';
+  choice?: string;
+  actor?: string;
+  reason?: string;
+}
+
+function isResolveMessage(v: unknown): v is ResolveMessage {
+  if (typeof v !== 'object' || v === null) return false;
+  const m = v as Record<string, unknown>;
+  return (
+    m['type'] === 'resolve' &&
+    typeof m['approvalId'] === 'string' &&
+    (m['outcome'] === 'approved' || m['outcome'] === 'rejected')
+  );
+}

package/src/approval.ts

@@ -0,0 +1,125 @@
+import { randomUUID } from 'crypto';
+import { nowISO } from './utils';
+
+// Approval types (ApprovalRequest, ApprovalDecision, ApprovalOutcome,
+// ApprovalEvent, ApprovalListener, ApprovalGateway) live in the shared
+// @tagma/types package so trigger plugins can import them without
+// depending on the engine's runtime implementation. This module keeps
+// only the in-memory implementation.
+import type {
+  ApprovalRequest, ApprovalDecision, ApprovalEvent, ApprovalListener, ApprovalGateway,
+} from '@tagma/types';
+
+// Re-export for existing engine-side consumers that import from this file.
+export type {
+  ApprovalRequest, ApprovalDecision, ApprovalOutcome, ApprovalEvent,
+  ApprovalListener, ApprovalGateway,
+} from '@tagma/types';
+
+// ═══ Default In-Memory Implementation ═══
+
+interface PendingEntry {
+  readonly request: ApprovalRequest;
+  readonly settle: (decision: ApprovalDecision) => void;
+  readonly timer: ReturnType<typeof setTimeout> | null;
+}
+
+export class InMemoryApprovalGateway implements ApprovalGateway {
+  private readonly pendingMap = new Map<string, PendingEntry>();
+  private readonly listeners = new Set<ApprovalListener>();
+
+  request(
+    req: Omit<ApprovalRequest, 'id' | 'createdAt' | 'options'> & { options?: readonly string[] },
+  ): Promise<ApprovalDecision> {
+    const full: ApprovalRequest = {
+      id: randomUUID(),
+      createdAt: nowISO(),
+      taskId: req.taskId,
+      trackId: req.trackId,
+      message: req.message,
+      options: req.options && req.options.length > 0 ? req.options : ['approve', 'reject'],
+      timeoutMs: req.timeoutMs,
+      metadata: req.metadata,
+    };
+
+    return new Promise<ApprovalDecision>((resolvePromise) => {
+      let timer: ReturnType<typeof setTimeout> | null = null;
+      if (full.timeoutMs > 0) {
+        timer = setTimeout(() => {
+          const entry = this.pendingMap.get(full.id);
+          if (!entry) return;
+          this.pendingMap.delete(full.id);
+          const decision: ApprovalDecision = {
+            approvalId: full.id,
+            outcome: 'timeout',
+            reason: `Approval timed out after ${full.timeoutMs}ms`,
+            decidedAt: nowISO(),
+          };
+          this.emit({ type: 'expired', request: full });
+          resolvePromise(decision);
+        }, full.timeoutMs);
+      }
+
+      this.pendingMap.set(full.id, { request: full, settle: resolvePromise, timer });
+      this.emit({ type: 'requested', request: full });
+    });
+  }
+
+  resolve(
+    approvalId: string,
+    decision: Omit<ApprovalDecision, 'approvalId' | 'decidedAt'>,
+  ): boolean {
+    const entry = this.pendingMap.get(approvalId);
+    if (!entry) return false;
+    this.pendingMap.delete(approvalId);
+    if (entry.timer) clearTimeout(entry.timer);
+
+    const full: ApprovalDecision = {
+      approvalId,
+      outcome: decision.outcome,
+      choice: decision.choice,
+      actor: decision.actor,
+      reason: decision.reason,
+      decidedAt: nowISO(),
+    };
+    this.emit({ type: 'resolved', request: entry.request, decision: full });
+    entry.settle(full);
+    return true;
+  }
+
+  pending(): readonly ApprovalRequest[] {
+    return Array.from(this.pendingMap.values()).map((e) => e.request);
+  }
+
+  subscribe(listener: ApprovalListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  abortAll(reason: string): void {
+    const entries = Array.from(this.pendingMap.entries());
+    this.pendingMap.clear();
+    for (const [id, entry] of entries) {
+      if (entry.timer) clearTimeout(entry.timer);
+      this.emit({ type: 'aborted', request: entry.request, reason });
+      entry.settle({
+        approvalId: id,
+        outcome: 'aborted',
+        reason,
+        decidedAt: nowISO(),
+      });
+    }
+  }
+
+  private emit(event: ApprovalEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error('[approval gateway] listener error:', err);
+      }
+    }
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,37 @@
+import { registerPlugin } from './registry';
+
+// Built-in Drivers
+// Only claude-code is built in. Other drivers (codex, opencode) ship as
+// workspace plugins under plugins/ and must be declared in pipeline.yaml
+// via the `plugins` field, e.g.:
+//   plugins: ["@tagma/driver-codex", "@tagma/driver-opencode"]
+import { ClaudeCodeDriver } from './drivers/claude-code';
+
+// Built-in Triggers
+import { FileTrigger } from './triggers/file';
+import { ManualTrigger } from './triggers/manual';
+
+// Built-in Completions
+import { ExitCodeCompletion } from './completions/exit-code';
+import { FileExistsCompletion } from './completions/file-exists';
+import { OutputCheckCompletion } from './completions/output-check';
+
+// Built-in Middleware
+import { StaticContextMiddleware } from './middlewares/static-context';
+
+export function bootstrapBuiltins(): void {
+  // Drivers
+  registerPlugin('drivers', 'claude-code', ClaudeCodeDriver);
+
+  // Triggers
+  registerPlugin('triggers', 'file', FileTrigger);
+  registerPlugin('triggers', 'manual', ManualTrigger);
+
+  // Completions
+  registerPlugin('completions', 'exit_code', ExitCodeCompletion);
+  registerPlugin('completions', 'file_exists', FileExistsCompletion);
+  registerPlugin('completions', 'output_check', OutputCheckCompletion);
+
+  // Middlewares
+  registerPlugin('middlewares', 'static_context', StaticContextMiddleware);
+}

package/src/completions/exit-code.ts

@@ -0,0 +1,19 @@
+import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
+
+export const ExitCodeCompletion: CompletionPlugin = {
+  name: 'exit_code',
+
+  async check(config: Record<string, unknown>, result: TaskResult, _ctx: CompletionContext): Promise<boolean> {
+    const expected = config.expect ?? 0;
+
+    if (typeof expected === 'number') {
+      return result.exitCode === expected;
+    }
+    if (Array.isArray(expected) && expected.every((v) => typeof v === 'number')) {
+      return expected.includes(result.exitCode);
+    }
+    throw new Error(
+      `exit_code completion: "expect" must be a number or number[], got ${typeof expected}`
+    );
+  },
+};

package/src/completions/file-exists.ts

@@ -0,0 +1,39 @@
+import { stat } from 'node:fs/promises';
+import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
+import { validatePath } from '../utils';
+
+type Kind = 'file' | 'dir' | 'any';
+
+export const FileExistsCompletion: CompletionPlugin = {
+  name: 'file_exists',
+
+  async check(config: Record<string, unknown>, _result: TaskResult, ctx: CompletionContext): Promise<boolean> {
+    const filePath = config.path as string;
+    if (!filePath) throw new Error('file_exists completion: "path" is required');
+
+    const safePath = validatePath(filePath, ctx.workDir);
+
+    const kind = (config.kind as Kind | undefined) ?? 'any';
+    if (kind !== 'file' && kind !== 'dir' && kind !== 'any') {
+      throw new Error(`file_exists completion: "kind" must be "file" | "dir" | "any", got "${kind}"`);
+    }
+
+    const minSize = config.min_size;
+    if (minSize != null && (typeof minSize !== 'number' || minSize < 0)) {
+      throw new Error(`file_exists completion: "min_size" must be a non-negative number`);
+    }
+
+    try {
+      const st = await stat(safePath);
+      if (kind === 'file' && !st.isFile()) return false;
+      if (kind === 'dir' && !st.isDirectory()) return false;
+      if (typeof minSize === 'number' && st.isFile() && st.size < minSize) return false;
+      return true;
+    } catch (err: unknown) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT' || code === 'ENOTDIR') return false;
+      // Permission / IO errors should surface, not silently mean "missing"
+      throw err;
+    }
+  },
+};

package/src/completions/output-check.ts

@@ -0,0 +1,57 @@
+import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
+import { shellArgs, parseDuration } from '../utils';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export const OutputCheckCompletion: CompletionPlugin = {
+  name: 'output_check',
+
+  async check(config: Record<string, unknown>, result: TaskResult, ctx: CompletionContext): Promise<boolean> {
+    const checkCmd = config.check as string;
+    if (!checkCmd) throw new Error('output_check completion: "check" is required');
+
+    const timeoutMs = config.timeout != null
+      ? parseDuration(String(config.timeout))
+      : DEFAULT_TIMEOUT_MS;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    const proc = Bun.spawn(shellArgs(checkCmd) as string[], {
+      cwd: ctx.workDir,
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      signal: controller.signal,
+    });
+
+    try {
+      if (proc.stdin) {
+        try {
+          proc.stdin.write(result.stdout);
+          await proc.stdin.end();
+        } catch (err: unknown) {
+          // EPIPE is expected when the check process exits before reading all of stdin
+          // (e.g. `grep -q` exits on first match). Anything else is a real failure.
+          const code = (err as NodeJS.ErrnoException)?.code;
+          if (code !== 'EPIPE') throw err;
+        }
+      }
+
+      const exitCode = await proc.exited;
+
+      if (exitCode !== 0) {
+        try {
+          const stderr = await new Response(proc.stderr).text();
+          if (stderr.trim()) {
+            console.warn(`[output_check] "${checkCmd}" exit=${exitCode}: ${stderr.trim()}`);
+          }
+        } catch { /* ignore stderr read failures */ }
+      }
+
+      return exitCode === 0;
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+};