@tagma/sdk 0.1.2

package/src/dag.ts

@@ -0,0 +1,137 @@
+import type { PipelineConfig, TaskConfig, TrackConfig } from './types';
+
+export interface DagNode {
+  readonly taskId: string;   // fully qualified: track_id.task_id or just task_id
+  readonly task: TaskConfig;
+  readonly track: TrackConfig;
+  readonly dependsOn: readonly string[];
+}
+
+export interface Dag {
+  readonly nodes: ReadonlyMap<string, DagNode>;
+  readonly sorted: readonly string[];   // topological order
+}
+
+// Build a global task ID: for cross-track refs we use "track_id.task_id"
+// Within a track, bare "task_id" is also valid
+function qualifyId(trackId: string, taskId: string): string {
+  return `${trackId}.${taskId}`;
+}
+
+export function buildDag(config: PipelineConfig): Dag {
+  const nodes = new Map<string, DagNode>();
+  // Map bare task IDs to qualified IDs (for resolving unqualified refs)
+  const bareToQualified = new Map<string, string>();
+
+  // 1. Register all nodes
+  for (const track of config.tracks) {
+    for (const task of track.tasks) {
+      const qid = qualifyId(track.id, task.id);
+
+      if (nodes.has(qid)) {
+        throw new Error(`Duplicate task ID: "${qid}"`);
+      }
+
+      // Track bare ID → qualified. If same bare ID in multiple tracks, mark ambiguous
+      if (bareToQualified.has(task.id)) {
+        bareToQualified.set(task.id, '__ambiguous__');
+      } else {
+        bareToQualified.set(task.id, qid);
+      }
+
+      nodes.set(qid, {
+        taskId: qid,
+        task,
+        track,
+        dependsOn: [],  // filled below
+      });
+    }
+  }
+
+  // Helper to resolve a dependency ref to a qualified ID
+  function resolveRef(ref: string, fromTrackId: string): string {
+    // Already qualified (contains dot)
+    if (ref.includes('.')) {
+      if (!nodes.has(ref)) {
+        throw new Error(`Task reference "${ref}" not found`);
+      }
+      return ref;
+    }
+    // Try within same track first
+    const sameTrack = qualifyId(fromTrackId, ref);
+    if (nodes.has(sameTrack)) return sameTrack;
+    // Try global bare lookup
+    const global = bareToQualified.get(ref);
+    if (global && global !== '__ambiguous__') return global;
+    if (global === '__ambiguous__') {
+      throw new Error(
+        `Ambiguous task reference "${ref}" exists in multiple tracks. ` +
+        `Use "track_id.task_id" format.`
+      );
+    }
+    throw new Error(`Task reference "${ref}" not found`);
+  }
+
+  // 2. Resolve depends_on and continue_from to qualified IDs
+  for (const track of config.tracks) {
+    for (const task of track.tasks) {
+      const qid = qualifyId(track.id, task.id);
+      const deps: string[] = [];
+
+      if (task.depends_on) {
+        for (const dep of task.depends_on) {
+          deps.push(resolveRef(dep, track.id));
+        }
+      }
+      if (task.continue_from) {
+        const resolved = resolveRef(task.continue_from, track.id);
+        if (!deps.includes(resolved)) {
+          deps.push(resolved); // continue_from implies dependency
+        }
+      }
+
+      // Replace node with resolved deps
+      const node = nodes.get(qid)!;
+      nodes.set(qid, { ...node, dependsOn: deps });
+    }
+  }
+
+  // 3. Topological sort + cycle detection (Kahn's algorithm)
+  const inDegree = new Map<string, number>();
+  const adjacency = new Map<string, string[]>(); // parent → children
+
+  for (const [id] of nodes) {
+    inDegree.set(id, 0);
+    adjacency.set(id, []);
+  }
+
+  for (const [id, node] of nodes) {
+    for (const dep of node.dependsOn) {
+      adjacency.get(dep)!.push(id);
+      inDegree.set(id, (inDegree.get(id) ?? 0) + 1);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id);
+  }
+
+  const sorted: string[] = [];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    sorted.push(current);
+    for (const child of adjacency.get(current)!) {
+      const newDegree = inDegree.get(child)! - 1;
+      inDegree.set(child, newDegree);
+      if (newDegree === 0) queue.push(child);
+    }
+  }
+
+  if (sorted.length !== nodes.size) {
+    const remaining = [...nodes.keys()].filter(id => !sorted.includes(id));
+    throw new Error(`Circular dependency detected involving tasks: ${remaining.join(', ')}`);
+  }
+
+  return { nodes, sorted };
+}

package/src/drivers/claude-code.ts

@@ -0,0 +1,207 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, relative, dirname, join } from 'node:path';
+import type {
+  DriverPlugin, DriverCapabilities, DriverResultMeta,
+  TaskConfig, TrackConfig, DriverContext, SpawnSpec, Permissions,
+} from '../types';
+
+// Claude Code CLI reference: https://code.claude.com/docs/en/cli-reference
+
+const MODEL_MAP: Record<string, string> = {
+  high: 'opus', medium: 'sonnet', low: 'haiku',
+};
+
+function resolveModel(tier: string): string {
+  return MODEL_MAP[tier] ?? 'sonnet';
+}
+
+function resolveTools(permissions: Permissions): string {
+  const tools = ['Grep', 'Glob'];
+  if (permissions.read) tools.push('Read');
+  if (permissions.write) tools.push('Edit', 'Write');
+  if (permissions.execute) tools.push('Bash');
+  return tools.join(',');
+}
+
+// Maps our Permissions to Claude Code's --permission-mode. In print (-p) mode
+// Claude needs non-interactive permission handling:
+// - `bypassPermissions` skips all checks (required for reliable Bash automation
+//   under `execute: true`, matches the "full trust" semantics of that tier).
+// - `dontAsk` auto-denies anything outside `--allowedTools`, which is exactly
+//   what we want for read/write tiers: the allowedTools whitelist already
+//   enumerates what Claude may do, and dontAsk makes violations fail fast
+//   instead of hanging on a prompt no one can answer in headless mode.
+// See: https://code.claude.com/docs/en/permission-modes
+function resolvePermissionMode(permissions: Permissions): string {
+  if (permissions.execute) return 'bypassPermissions';
+  return 'dontAsk';
+}
+
+// Returns true if `sub` is inside `root` (or equal to it).
+function isInside(root: string, sub: string): boolean {
+  const rel = relative(root, sub);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+// Claude Code requires CLAUDE_CODE_GIT_BASH_PATH on Windows pointing to
+// Git Bash (bin\bash.exe under a Git for Windows install). See:
+//   https://code.claude.com/docs/en/troubleshooting#windows-claude-code-on-windows-requires-git-bash
+// The path must use native Windows backslashes — forward slashes are rejected
+// by Claude Code's path validation.
+function resolveGitBashEnv(): Record<string, string> {
+  if (process.platform !== 'win32') return {};
+
+  // Respect user-provided value if it points to an actual file. If the user
+  // set it to a non-existent path, fall through to discovery rather than
+  // propagating the broken config.
+  const existing = process.env.CLAUDE_CODE_GIT_BASH_PATH;
+  if (existing && existsSync(existing)) return {};
+
+  const discovered = discoverGitBash();
+  return discovered ? { CLAUDE_CODE_GIT_BASH_PATH: discovered } : {};
+}
+
+function discoverGitBash(): string | null {
+  // Strategy 1: find git.exe in PATH (equivalent to `where.exe git`) and
+  // walk up looking for bin\bash.exe under a Git install root. Git for
+  // Windows may expose multiple git.exe locations (cmd\git.exe,
+  // mingw64\bin\git.exe, mingw64\libexec\git-core\git.exe), so we walk up
+  // several levels rather than assuming a fixed depth.
+  const gitExe = findExeInPath('git.exe');
+  if (gitExe) {
+    let dir = dirname(gitExe);
+    for (let depth = 0; depth < 5; depth++) {
+      const candidate = join(dir, 'bin', 'bash.exe');
+      if (existsSync(candidate)) return candidate;
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+
+  // Strategy 2: check common Git for Windows install locations.
+  // Uses %ProgramFiles%/%LOCALAPPDATA%/%USERPROFILE% env vars so it works on
+  // systems where those aren't mapped to C:\ (e.g. localized Windows).
+  const programFiles = process.env['ProgramFiles'] ?? 'C:\\Program Files';
+  const programFilesX86 = process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+  const localAppData = process.env['LOCALAPPDATA'];
+  const userProfile = process.env['USERPROFILE'];
+
+  const candidates = [
+    join(programFiles, 'Git', 'bin', 'bash.exe'),
+    join(programFilesX86, 'Git', 'bin', 'bash.exe'),
+    // Git for Windows user-level install
+    localAppData && join(localAppData, 'Programs', 'Git', 'bin', 'bash.exe'),
+    // Scoop
+    userProfile && join(userProfile, 'scoop', 'apps', 'git', 'current', 'bin', 'bash.exe'),
+    // Chocolatey default
+    'C:\\tools\\git\\bin\\bash.exe',
+  ].filter((p): p is string => Boolean(p));
+
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+
+  // Strategy 3: scan PATH for any entry containing "git" (e.g. Git's
+  // mingw64/bin or usr/bin already in PATH), walk up to find bash.exe.
+  // Catches custom install locations.
+  const pathEntries = (process.env.PATH ?? '').split(';');
+  for (const entry of pathEntries) {
+    if (!/git/i.test(entry)) continue;
+    const normalized = entry.replace(/\//g, '\\').replace(/\\+$/, '');
+    const parts = normalized.split('\\');
+    for (let depth = 1; depth <= 4; depth++) {
+      const root = parts.slice(0, parts.length - depth).join('\\');
+      if (!root) continue;
+      const candidate = root + '\\bin\\bash.exe';
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+function findExeInPath(exe: string): string | null {
+  const pathDirs = (process.env.PATH ?? '').split(';');
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const full = join(dir, exe);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+
+export const ClaudeCodeDriver: DriverPlugin = {
+  name: 'claude-code',
+
+  capabilities: {
+    sessionResume: true,
+    systemPrompt: true,
+    outputFormat: true,
+  } satisfies DriverCapabilities,
+
+  resolveModel,
+  resolveTools,
+
+  async buildCommand(
+    task: TaskConfig, track: TrackConfig, ctx: DriverContext,
+  ): Promise<SpawnSpec> {
+    const permissions = task.permissions ?? track.permissions!;
+    const model = resolveModel(task.model_tier ?? track.model_tier ?? 'medium');
+    const tools = resolveTools(permissions);
+    const permissionMode = resolvePermissionMode(permissions);
+
+    const args: string[] = [
+      'claude',
+      '-p', task.prompt!,
+      '--model', model,
+      '--allowedTools', tools,
+      '--permission-mode', permissionMode,
+      '--output-format', 'json',
+      '--verbose',
+      // Pin to project+local settings only; don't inherit arbitrary user-level
+      // config (hooks, MCP servers, etc.) into pipeline automation.
+      '--setting-sources', 'project,local',
+    ];
+
+    const profile = task.agent_profile ?? track.agent_profile;
+    if (profile) {
+      args.push('--append-system-prompt', profile);
+    }
+
+    // If the task runs in a subdirectory of the project, grant read/edit
+    // access to the project root via --add-dir so Claude can still see
+    // shared files (configs, types, etc.) outside task.cwd.
+    const effectiveCwd = task.cwd ?? ctx.workDir;
+    if (effectiveCwd !== ctx.workDir && isInside(ctx.workDir, effectiveCwd)) {
+      args.push('--add-dir', ctx.workDir);
+    }
+
+    // Native session resume
+    if (task.continue_from) {
+      const sessionId = ctx.sessionMap.get(task.continue_from);
+      if (sessionId) {
+        args.push('--resume', sessionId);
+      }
+    }
+
+    return { args, cwd: effectiveCwd, env: resolveGitBashEnv() };
+  },
+
+  parseResult(stdout: string): DriverResultMeta {
+    try {
+      const json = JSON.parse(stdout);
+      // Extract canonical text: strip JSON envelope so downstream drivers
+      // get the actual AI response, not metadata
+      const normalizedOutput = json.result ?? json.text ?? json.content ?? stdout;
+      return {
+        sessionId: json.session_id,
+        normalizedOutput: typeof normalizedOutput === 'string'
+          ? normalizedOutput
+          : JSON.stringify(normalizedOutput),
+      };
+    } catch {
+      return { normalizedOutput: stdout };
+    }
+  },
+};