@tagma/sdk 0.2.3 → 0.2.5

package/README.md

@@ -60,7 +60,8 @@ console.log(result.success ? 'Done' : 'Failed');
 - **Lifecycle hooks** -- `pipeline_start`, `task_start`, `task_success`, `task_failure`, `pipeline_complete`, `pipeline_error`
 - **Middleware** -- enrich prompts before execution (e.g. inject static context)
 - **Completion checks** -- validate task output with `exit_code`, `file_exists`, or `output_check` plugins
-- **Template expansion** -- reusable task templates with parameterized `use` / `with`
+- **Template expansion** -- reusable task templates with parameterized `use` / `with`; `discoverTemplates()` enumerates installed `@tagma/template-*` packages for editor integrations
+- **Plugin schemas** -- triggers/completions/middlewares can declare a `PluginSchema` so visual editors render typed forms for their config
 
 ## Pipeline YAML Reference
 
@@ -333,6 +334,27 @@ Dynamically loads and registers external plugin packages.
 
 Registers a plugin handler manually. Idempotent — duplicate registrations are silently ignored.
 
+Plugin handlers (`TriggerPlugin`, `CompletionPlugin`, `MiddlewarePlugin`) may optionally expose a declarative `schema: PluginSchema` field so visual editors can render a typed form for the plugin's config instead of a raw key/value editor:
+
+```ts
+import type { TriggerPlugin } from '@tagma/types';
+
+export const HttpTrigger: TriggerPlugin = {
+  name: 'http',
+  schema: {
+    description: 'Wait for an HTTP endpoint to return 2xx before the task runs.',
+    fields: {
+      url:    { type: 'string', required: true, placeholder: 'https://...' },
+      method: { type: 'enum',   enum: ['GET', 'POST'], default: 'GET' },
+      timeout:{ type: 'duration', description: 'Give up after this long.' },
+    },
+  },
+  async watch(config, ctx) { /* ... */ },
+};
+```
+
+The schema is purely descriptive — plugins still perform their own runtime validation. Supported field types: `string`, `number`, `boolean`, `enum`, `path`, `duration`, `number-or-list`. Each field can declare `required`, `default`, `description`, `enum`, `min`/`max`, `placeholder`. Built-in plugins (`file`/`manual` triggers; `exit_code`/`file_exists`/`output_check` completions; `static_context` middleware) all ship with schemas so editors can generate forms out of the box.
+
 ### `getHandler(category, type): PluginType`
 
 Retrieves a registered plugin handler. Throws if the plugin is not registered.
@@ -355,6 +377,25 @@ Use `loadPipeline` for the common parse-and-resolve flow. Use `resolveConfig` di
 
 Expands `use:` template references in a task list. Loads template packages (`@tagma/template-*`), resolves parameters, and namespaces task IDs and dependencies. Called internally by `loadPipeline`.
 
+### `discoverTemplates(workDir: string): TemplateManifest[]`
+
+Scans `<workDir>/node_modules/@tagma/` for installed `template-*` packages and returns their manifests (name, description, params, ref). Intended for editors/UIs that want to render a "pick a template" browser without actually expanding any templates. Silently skips packages whose `template.yaml` is missing or invalid.
+
+```ts
+import { discoverTemplates } from '@tagma/sdk';
+
+const templates = discoverTemplates(process.cwd());
+// [{ ref: '@tagma/template-review', name: 'Code Review', description: '...', params: {...}, tasks: [...] }, ...]
+```
+
+Each `TemplateManifest` is a `TemplateConfig` with an extra `ref` field — the value users drop into `task.use`.
+
+### `loadTemplateManifest(ref: string, workDir: string): TemplateManifest | null`
+
+Loads a single template's manifest by ref (e.g. `@tagma/template-review`). Returns `null` when the package isn't installed or its manifest fails to parse. Complements `discoverTemplates` when the caller only needs one template.
+
+Both functions use Node's `fs` APIs and are safe to call from Node runtimes (unlike the legacy Bun-only `loadTemplate` used internally by `expandTemplates`).
+
 ### `attachStdinApprovalAdapter(gateway): StdinApprovalAdapter`
 
 Attaches an interactive stdin-based approval handler.

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.2.3",
+  "version": "0.2.5",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GoTagma/tagma-sdk.git"
+  },
   "type": "module",
   "workspaces": [
     "plugins/*"

package/src/adapters/stdin-approval.ts

@@ -1,117 +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;
-      }
-    },
-  };
-}
+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/completions/exit-code.ts

@@ -1,19 +1,30 @@
-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}`
-    );
-  },
-};
+import type { CompletionPlugin, CompletionContext, TaskResult } from '../types';
+
+export const ExitCodeCompletion: CompletionPlugin = {
+  name: 'exit_code',
+  schema: {
+    description: 'Mark the task successful when the exit code matches.',
+    fields: {
+      expect: {
+        type: 'number-or-list',
+        default: 0,
+        description: 'Expected exit code, or list of acceptable codes (e.g. 0 or [0, 2]).',
+        placeholder: '0',
+      },
+    },
+  },
+
+  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

@@ -1,39 +1,60 @@
-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;
-    }
-  },
-};
+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',
+  schema: {
+    description: 'Mark the task successful when a target file or directory exists.',
+    fields: {
+      path: {
+        type: 'path',
+        required: true,
+        description: 'Path to check (relative to workDir or absolute).',
+      },
+      kind: {
+        type: 'enum',
+        enum: ['file', 'dir', 'any'],
+        default: 'any',
+        description: 'Restrict to a file, directory, or accept either.',
+      },
+      min_size: {
+        type: 'number',
+        min: 0,
+        description: 'Optional minimum size in bytes (files only).',
+      },
+    },
+  },
+
+  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

@@ -5,6 +5,23 @@ const DEFAULT_TIMEOUT_MS = 30_000;
 
 export const OutputCheckCompletion: CompletionPlugin = {
   name: 'output_check',
+  schema: {
+    description: 'Pipe task stdout into a shell command; mark success when that command exits 0.',
+    fields: {
+      check: {
+        type: 'string',
+        required: true,
+        description: 'Shell command to run. Task stdout is piped to its stdin.',
+        placeholder: "grep -q 'PASS'",
+      },
+      timeout: {
+        type: 'duration',
+        default: '30s',
+        description: 'Maximum time to wait for the check command.',
+        placeholder: '30s',
+      },
+    },
+  },
 
   async check(config: Record<string, unknown>, result: TaskResult, ctx: CompletionContext): Promise<boolean> {
     const checkCmd = config.check as string;

package/src/dag.ts

@@ -1,222 +1,222 @@
-import type { PipelineConfig, RawPipelineConfig, RawTaskConfig, 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 };
-}
-
-// ═══ Raw DAG (for visual editor — no workDir required) ═══
-
-export interface RawDagNode {
-  readonly taskId: string;        // fully qualified: track_id.task_id
-  readonly trackId: string;
-  readonly rawTask: RawTaskConfig;
-  readonly dependsOn: readonly string[];  // fully qualified IDs, best-effort resolved
-}
-
-export interface RawDag {
-  readonly nodes: ReadonlyMap<string, RawDagNode>;
-  /** Directed edges: from → to means "from must complete before to starts" */
-  readonly edges: readonly { readonly from: string; readonly to: string }[];
-}
-
-/**
- * Build a lightweight DAG from a raw (unresolved) pipeline config.
- * Unlike buildDag, this function:
- *   - Does not require a workDir or resolved PipelineConfig
- *   - Is lenient: missing or ambiguous refs are silently skipped
- *   - Skips template-expansion tasks (those with a `use` field)
- *
- * Intended for the visual editor to render the flow graph before a pipeline is run.
- */
-export function buildRawDag(config: RawPipelineConfig): RawDag {
-  const nodes = new Map<string, RawDagNode>();
-  const bareToQualified = new Map<string, string>();
-
-  // 1. Register all concrete tasks
-  for (const track of config.tracks) {
-    for (const task of track.tasks) {
-      if (task.use) continue; // template-expansion tasks are not yet materialized
-      const qid = `${track.id}.${task.id}`;
-      if (nodes.has(qid)) continue; // skip duplicates silently
-
-      if (bareToQualified.has(task.id)) {
-        bareToQualified.set(task.id, '__ambiguous__');
-      } else {
-        bareToQualified.set(task.id, qid);
-      }
-      nodes.set(qid, { taskId: qid, trackId: track.id, rawTask: task, dependsOn: [] });
-    }
-  }
-
-  // 2. Resolve dependency refs leniently (missing / ambiguous refs are skipped)
-  function tryResolve(ref: string, fromTrackId: string): string | null {
-    if (ref.includes('.')) return nodes.has(ref) ? ref : null;
-    const sameTrack = `${fromTrackId}.${ref}`;
-    if (nodes.has(sameTrack)) return sameTrack;
-    const global = bareToQualified.get(ref);
-    if (global && global !== '__ambiguous__') return global;
-    return null;
-  }
-
-  const edges: { from: string; to: string }[] = [];
-
-  for (const track of config.tracks) {
-    for (const task of track.tasks) {
-      if (task.use) continue;
-      const qid = `${track.id}.${task.id}`;
-      const deps: string[] = [];
-
-      for (const ref of task.depends_on ?? []) {
-        const resolved = tryResolve(ref, track.id);
-        if (resolved && !deps.includes(resolved)) {
-          deps.push(resolved);
-          edges.push({ from: resolved, to: qid });
-        }
-      }
-      if (task.continue_from) {
-        const resolved = tryResolve(task.continue_from, track.id);
-        if (resolved && !deps.includes(resolved)) {
-          deps.push(resolved);
-          edges.push({ from: resolved, to: qid });
-        }
-      }
-
-      const node = nodes.get(qid)!;
-      nodes.set(qid, { ...node, dependsOn: deps });
-    }
-  }
-
-  return { nodes, edges };
-}
+import type { PipelineConfig, RawPipelineConfig, RawTaskConfig, 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 };
+}
+
+// ═══ Raw DAG (for visual editor — no workDir required) ═══
+
+export interface RawDagNode {
+  readonly taskId: string;        // fully qualified: track_id.task_id
+  readonly trackId: string;
+  readonly rawTask: RawTaskConfig;
+  readonly dependsOn: readonly string[];  // fully qualified IDs, best-effort resolved
+}
+
+export interface RawDag {
+  readonly nodes: ReadonlyMap<string, RawDagNode>;
+  /** Directed edges: from → to means "from must complete before to starts" */
+  readonly edges: readonly { readonly from: string; readonly to: string }[];
+}
+
+/**
+ * Build a lightweight DAG from a raw (unresolved) pipeline config.
+ * Unlike buildDag, this function:
+ *   - Does not require a workDir or resolved PipelineConfig
+ *   - Is lenient: missing or ambiguous refs are silently skipped
+ *   - Skips template-expansion tasks (those with a `use` field)
+ *
+ * Intended for the visual editor to render the flow graph before a pipeline is run.
+ */
+export function buildRawDag(config: RawPipelineConfig): RawDag {
+  const nodes = new Map<string, RawDagNode>();
+  const bareToQualified = new Map<string, string>();
+
+  // 1. Register all concrete tasks
+  for (const track of config.tracks) {
+    for (const task of track.tasks) {
+      if (task.use) continue; // template-expansion tasks are not yet materialized
+      const qid = `${track.id}.${task.id}`;
+      if (nodes.has(qid)) continue; // skip duplicates silently
+
+      if (bareToQualified.has(task.id)) {
+        bareToQualified.set(task.id, '__ambiguous__');
+      } else {
+        bareToQualified.set(task.id, qid);
+      }
+      nodes.set(qid, { taskId: qid, trackId: track.id, rawTask: task, dependsOn: [] });
+    }
+  }
+
+  // 2. Resolve dependency refs leniently (missing / ambiguous refs are skipped)
+  function tryResolve(ref: string, fromTrackId: string): string | null {
+    if (ref.includes('.')) return nodes.has(ref) ? ref : null;
+    const sameTrack = `${fromTrackId}.${ref}`;
+    if (nodes.has(sameTrack)) return sameTrack;
+    const global = bareToQualified.get(ref);
+    if (global && global !== '__ambiguous__') return global;
+    return null;
+  }
+
+  const edges: { from: string; to: string }[] = [];
+
+  for (const track of config.tracks) {
+    for (const task of track.tasks) {
+      if (task.use) continue;
+      const qid = `${track.id}.${task.id}`;
+      const deps: string[] = [];
+
+      for (const ref of task.depends_on ?? []) {
+        const resolved = tryResolve(ref, track.id);
+        if (resolved && !deps.includes(resolved)) {
+          deps.push(resolved);
+          edges.push({ from: resolved, to: qid });
+        }
+      }
+      if (task.continue_from) {
+        const resolved = tryResolve(task.continue_from, track.id);
+        if (resolved && !deps.includes(resolved)) {
+          deps.push(resolved);
+          edges.push({ from: resolved, to: qid });
+        }
+      }
+
+      const node = nodes.get(qid)!;
+      nodes.set(qid, { ...node, dependsOn: deps });
+    }
+  }
+
+  return { nodes, edges };
+}

package/src/middlewares/static-context.ts

@@ -1,29 +1,45 @@
-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}`;
-  },
-};
+import { basename } from 'path';
+import type { MiddlewarePlugin, MiddlewareContext } from '../types';
+import { validatePath } from '../utils';
+
+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 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/sdk.ts

@@ -32,6 +32,10 @@ export type { ValidationError } from './validate-raw';
 // ── Schema: parse / resolve / load / serialize / validate ──
 export { parseYaml, resolveConfig, expandTemplates, loadPipeline, serializePipeline, deresolvePipeline, validateConfig } from './schema';
 
+// ── Templates: discovery + manifest loading (F1) ──
+export { discoverTemplates, loadTemplateManifest } from './templates';
+export type { TemplateManifest } from './templates';
+
 // ── DAG ──
 export { buildDag, buildRawDag } from './dag';
 export type { DagNode, Dag, RawDagNode, RawDag } from './dag';

package/src/templates.ts

@@ -0,0 +1,97 @@
+// ═══ Template Discovery (F1) ═══
+//
+// Public helpers so editors / UIs can enumerate installed `@tagma/template-*`
+// packages in a workspace and read each template's declarative metadata
+// (name, description, params) without actually expanding the template.
+//
+// The legacy private `loadTemplate` in schema.ts uses Bun-specific APIs
+// (Bun.file, require.resolve). These helpers are Node-compatible because
+// the editor server runs on Node, not Bun.
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import yaml from 'js-yaml';
+import type { TemplateConfig } from './types';
+
+export interface TemplateManifest extends TemplateConfig {
+  /** The package ref as it would appear in `task.use`, e.g. `@tagma/template-review`. */
+  readonly ref: string;
+}
+
+/**
+ * Scan the workspace's `node_modules/@tagma/*` for packages whose name starts
+ * with `template-` and load each one's manifest. Packages without a valid
+ * `template.yaml` (or that fail to parse) are silently skipped.
+ *
+ * Returns an empty array when `workDir` doesn't exist or has no such packages.
+ */
+export function discoverTemplates(workDir: string): TemplateManifest[] {
+  const out: TemplateManifest[] = [];
+  const scopeDir = join(workDir, 'node_modules', '@tagma');
+  if (!existsSync(scopeDir)) return out;
+
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(scopeDir);
+  } catch {
+    return out;
+  }
+
+  for (const entry of entries) {
+    if (!entry.startsWith('template-')) continue;
+    const pkgDir = join(scopeDir, entry);
+    try {
+      const st = statSync(pkgDir);
+      if (!st.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+
+    const ref = `@tagma/${entry}`;
+    const manifest = loadTemplateManifestFromDir(pkgDir, ref);
+    if (manifest) out.push(manifest);
+  }
+
+  // Sort alphabetically for deterministic UI rendering.
+  out.sort((a, b) => a.ref.localeCompare(b.ref));
+  return out;
+}
+
+/**
+ * Load a single template's manifest by its ref (e.g. `@tagma/template-review`)
+ * from the given workspace's `node_modules`. Returns `null` if the package
+ * isn't installed or its manifest can't be parsed.
+ */
+export function loadTemplateManifest(ref: string, workDir: string): TemplateManifest | null {
+  // Only @tagma/template-* refs are supported (matches SDK validateTemplateRef).
+  const stripped = ref.replace(/@v\d+$/, '');
+  if (!stripped.startsWith('@tagma/template-')) return null;
+  const pkgDir = join(workDir, 'node_modules', stripped);
+  if (!existsSync(pkgDir)) return null;
+  return loadTemplateManifestFromDir(pkgDir, stripped);
+}
+
+/**
+ * Resolve a template manifest from an absolute package directory. Tries
+ * `template.yaml` first (the documented convention), then a `template` export
+ * from `package.json`'s `main`. Returns `null` on any failure so discovery
+ * stays robust against malformed packages.
+ */
+function loadTemplateManifestFromDir(pkgDir: string, ref: string): TemplateManifest | null {
+  const yamlPath = join(pkgDir, 'template.yaml');
+  if (existsSync(yamlPath)) {
+    try {
+      const content = readFileSync(yamlPath, 'utf-8');
+      const doc = yaml.load(content) as { template?: TemplateConfig } | TemplateConfig;
+      const tpl = (doc && typeof doc === 'object' && 'template' in doc
+        ? (doc as { template?: TemplateConfig }).template
+        : (doc as TemplateConfig)) as TemplateConfig | undefined;
+      if (tpl && typeof tpl === 'object' && tpl.name && Array.isArray(tpl.tasks)) {
+        return { ...tpl, ref };
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}

package/src/triggers/file.ts

@@ -11,6 +11,22 @@ function pathsEqual(a: string, b: string): boolean {
 
 export const FileTrigger: TriggerPlugin = {
   name: 'file',
+  schema: {
+    description: 'Wait for a file to appear or be modified before the task runs.',
+    fields: {
+      path: {
+        type: 'path',
+        required: true,
+        description: 'Path to the file to watch (relative to workDir or absolute).',
+        placeholder: 'e.g. build/output.json',
+      },
+      timeout: {
+        type: 'duration',
+        description: 'Maximum wait time (e.g. 30s, 5m). Omit or 0 to wait indefinitely.',
+        placeholder: '30s',
+      },
+    },
+  },
 
   watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
     const filePath = config.path as string;

package/src/triggers/manual.ts

@@ -1,61 +1,81 @@
-import type { TriggerPlugin, TriggerContext } from '../types';
-import { parseDuration } from '../utils';
-
-export const ManualTrigger: TriggerPlugin = {
-  name: 'manual',
-
-  async watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
-    const message =
-      (config.message as string | undefined) ?? `Manual confirmation required for task "${ctx.taskId}"`;
-    const timeoutMs = config.timeout ? parseDuration(config.timeout as string) : 0;
-    const options = Array.isArray(config.options)
-      ? (config.options as unknown[]).map(String)
-      : undefined;
-    const metadata =
-      config.metadata && typeof config.metadata === 'object'
-        ? (config.metadata as Record<string, unknown>)
-        : undefined;
-
-    const decisionPromise = ctx.approvalGateway.request({
-      taskId: ctx.taskId,
-      trackId: ctx.trackId,
-      message,
-      options,
-      timeoutMs,
-      metadata,
-    });
-
-    // Wire AbortSignal → try to resolve this specific request as aborted.
-    // We can't directly cancel via the gateway (no id yet at .request() call site),
-    // so instead we race against an abort promise and let engine status logic
-    // fall back to pipelineAborted → skipped. abortAll() on gateway still runs
-    // from engine shutdown path to clean up any truly-pending entries.
-    const abortPromise = new Promise<never>((_, reject) => {
-      if (ctx.signal.aborted) {
-        reject(new Error('Pipeline aborted'));
-        return;
-      }
-      ctx.signal.addEventListener(
-        'abort',
-        () => reject(new Error('Pipeline aborted')),
-        { once: true },
-      );
-    });
-
-    const decision = await Promise.race([decisionPromise, abortPromise]);
-
-    switch (decision.outcome) {
-      case 'approved':
-        return { confirmed: true, approvalId: decision.approvalId, choice: decision.choice, actor: decision.actor };
-      case 'rejected':
-        throw new Error(
-          `Manual trigger rejected by ${decision.actor ?? 'user'}` +
-            (decision.reason ? `: ${decision.reason}` : ''),
-        );
-      case 'timeout':
-        throw new Error(`Manual trigger timeout: ${decision.reason ?? 'no decision made'}`);
-      case 'aborted':
-        throw new Error(`Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`);
-    }
-  },
-};
+import type { TriggerPlugin, TriggerContext } from '../types';
+import { parseDuration } from '../utils';
+
+export const ManualTrigger: TriggerPlugin = {
+  name: 'manual',
+  schema: {
+    description: 'Pause the task until a user approves via the approval gateway.',
+    fields: {
+      message: {
+        type: 'string',
+        description: 'Prompt shown to the approver. Defaults to a generic message if empty.',
+        placeholder: 'Confirm deployment to production?',
+      },
+      timeout: {
+        type: 'duration',
+        description: 'Maximum wait time (e.g. 10m). Omit or 0 to wait indefinitely.',
+        placeholder: '10m',
+      },
+      options: {
+        type: 'string',
+        description: 'Comma-separated list of choices offered to the approver (e.g. "yes,no,defer").',
+        placeholder: 'yes,no',
+      },
+    },
+  },
+
+  async watch(config: Record<string, unknown>, ctx: TriggerContext): Promise<unknown> {
+    const message =
+      (config.message as string | undefined) ?? `Manual confirmation required for task "${ctx.taskId}"`;
+    const timeoutMs = config.timeout ? parseDuration(config.timeout as string) : 0;
+    const options = Array.isArray(config.options)
+      ? (config.options as unknown[]).map(String)
+      : undefined;
+    const metadata =
+      config.metadata && typeof config.metadata === 'object'
+        ? (config.metadata as Record<string, unknown>)
+        : undefined;
+
+    const decisionPromise = ctx.approvalGateway.request({
+      taskId: ctx.taskId,
+      trackId: ctx.trackId,
+      message,
+      options,
+      timeoutMs,
+      metadata,
+    });
+
+    // Wire AbortSignal → try to resolve this specific request as aborted.
+    // We can't directly cancel via the gateway (no id yet at .request() call site),
+    // so instead we race against an abort promise and let engine status logic
+    // fall back to pipelineAborted → skipped. abortAll() on gateway still runs
+    // from engine shutdown path to clean up any truly-pending entries.
+    const abortPromise = new Promise<never>((_, reject) => {
+      if (ctx.signal.aborted) {
+        reject(new Error('Pipeline aborted'));
+        return;
+      }
+      ctx.signal.addEventListener(
+        'abort',
+        () => reject(new Error('Pipeline aborted')),
+        { once: true },
+      );
+    });
+
+    const decision = await Promise.race([decisionPromise, abortPromise]);
+
+    switch (decision.outcome) {
+      case 'approved':
+        return { confirmed: true, approvalId: decision.approvalId, choice: decision.choice, actor: decision.actor };
+      case 'rejected':
+        throw new Error(
+          `Manual trigger rejected by ${decision.actor ?? 'user'}` +
+            (decision.reason ? `: ${decision.reason}` : ''),
+        );
+      case 'timeout':
+        throw new Error(`Manual trigger timeout: ${decision.reason ?? 'no decision made'}`);
+      case 'aborted':
+        throw new Error(`Manual trigger aborted: ${decision.reason ?? 'pipeline aborted'}`);
+    }
+  },
+};