@tagma/sdk 0.2.4 → 0.2.6

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
 
@@ -117,7 +118,6 @@ pipeline:
           trigger:
             type: manual
             message: "Approve before running"
-            options: [approve, reject]
             timeout: 5m
           completion:
             type: exit_code
@@ -223,7 +223,6 @@ Track-level `middlewares` apply to all tasks in the track. Setting task-level `m
 |---|---|---|---|---|
 | `type` | `"manual"` | Yes | — | Trigger type |
 | `message` | `string` | No | `"Manual confirmation required for task \"{taskId}\""` | Message shown to the approver |
-| `options` | `string[]` | No | — | Choice options (e.g. `[approve, reject]`) |
 | `timeout` | `string` | No | — | How long to wait for a decision before timing out |
 | `metadata` | `object` | No | — | Arbitrary metadata passed to the approval gateway |
 
@@ -295,6 +294,7 @@ Options:
 - `onEvent` -- callback for real-time `PipelineEvent` updates:
   - `pipeline_start` — pipeline began; includes `states: ReadonlyMap<taskId, TaskState>` (initial snapshot of all tasks at `waiting`)
   - `task_status_change` — a task changed status; includes `state: TaskState` (complete snapshot at the time of change: `startedAt` is populated before the `running` event; `result` and `finishedAt` are populated before any terminal-status event)
+  - `task_log` — a structured log line was written to `pipeline.log`. Mirrors every `Logger` call (info/warn/error/debug/section/quiet) and carries `{ taskId: string | null, level, timestamp, text }`. `taskId` is non-null for lines tagged with a `[task:<id>]` prefix (or passed explicitly to `section`/`quiet`) and `null` for pipeline-wide messages such as the configuration dump and DAG topology. Use this to stream the full run process into UIs without tailing the log file.
   - `pipeline_end` — pipeline finished; includes `success: boolean`
 - `maxLogRuns` -- number of per-run log directories to keep under `<workDir>/.tagma/logs/` (default: 20)
 
@@ -333,6 +333,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 +376,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.
@@ -465,9 +505,31 @@ logger.warn('[track]', 'message');   // console + file
 logger.error('[track]', 'message');  // console + file
 logger.debug('[track]', 'message');  // file only
 logger.section('Title');             // file only — visual separator
-logger.quiet(bulkText);             // file only — bulk payload
-logger.path;                        // log file path
-logger.dir;                         // run artifact directory
+logger.quiet(bulkText);              // file only — bulk payload
+logger.path;                         // log file path
+logger.dir;                          // run artifact directory
+```
+
+Pass an optional third argument to stream every appended line out as a
+structured `LogRecord` — `runPipeline` uses this to emit `task_log` events:
+
+```ts
+import { Logger, type LogRecord } from '@tagma/sdk';
+
+const logger = new Logger(workDir, runId, (record: LogRecord) => {
+  // record = { level, taskId, timestamp, text }
+  // level  = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet'
+  // taskId is extracted from a '[task:<id>]' prefix, or null for untagged lines
+  forwardToUI(record);
+});
+```
+
+`section` and `quiet` carry no prefix, so pass an explicit `taskId` when the
+line logically belongs to a task — the extractor cannot infer one otherwise:
+
+```ts
+logger.section(`Task ${taskId}`, taskId);
+logger.quiet(`--- stdout (${taskId}) ---\n${body}\n--- end stdout ---`, taskId);
 ```
 
 ### `tailLines(text: string, n: number): string`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tagma/sdk",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/adapters/stdin-approval.ts

@@ -1,117 +1,106 @@
-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;
+
+        process.stdout.write(
+          `\n[APPROVAL REQUIRED] ${req.message}\n` +
+            `  id:      ${req.id}\n` +
+            `  task:    ${req.taskId}${req.trackId ? ` (track: ${req.trackId})` : ''}\n` +
+            `  approve / reject > `,
+        );
+
+        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']);
+
+        if (approveAliases.has(input)) {
+          gateway.resolve(req.id, { outcome: 'approved', actor: 'cli' });
+        } else if (rejectAliases.has(input)) {
+          gateway.resolve(req.id, {
+            outcome: 'rejected',
+            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

@@ -16,7 +16,7 @@ import type { ApprovalGateway, ApprovalEvent } from '../approval';
 //
 // Protocol — client → server:
 //   { type: 'resolve', approvalId: string, outcome: 'approved'|'rejected',
-//     choice?: string, actor?: string, reason?: string }
+//     actor?: string, reason?: string }
 
 export interface WebSocketApprovalAdapterOptions {
   port?: number;      // default: 3000
@@ -123,7 +123,6 @@ export function attachWebSocketApprovalAdapter(
 
         const ok = gateway.resolve(msg.approvalId, {
           outcome: msg.outcome,
-          choice: msg.choice,
           actor: msg.actor ?? 'websocket',
           reason: msg.reason,
         });
@@ -159,7 +158,6 @@ interface ResolveMessage {
   type: 'resolve';
   approvalId: string;
   outcome: 'approved' | 'rejected';
-  choice?: string;
   actor?: string;
   reason?: string;
 }

package/src/approval.ts

@@ -16,9 +16,6 @@ export type {
   ApprovalListener, ApprovalGateway,
 } from '@tagma/types';
 
-// Default options presented to the approver when the caller does not specify any.
-const DEFAULT_APPROVAL_OPTIONS = ['approve', 'reject'] as const;
-
 // ═══ Default In-Memory Implementation ═══
 
 interface PendingEntry {
@@ -32,7 +29,7 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
   private readonly listeners = new Set<ApprovalListener>();
 
   request(
-    req: Omit<ApprovalRequest, 'id' | 'createdAt' | 'options'> & { options?: readonly string[] },
+    req: Omit<ApprovalRequest, 'id' | 'createdAt'>,
   ): Promise<ApprovalDecision> {
     const full: ApprovalRequest = {
       id: randomUUID(),
@@ -40,7 +37,6 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
       taskId: req.taskId,
       trackId: req.trackId,
       message: req.message,
-      options: req.options && req.options.length > 0 ? req.options : DEFAULT_APPROVAL_OPTIONS,
       timeoutMs: req.timeoutMs,
       metadata: req.metadata,
     };
@@ -80,7 +76,6 @@ export class InMemoryApprovalGateway implements ApprovalGateway {
     const full: ApprovalDecision = {
       approvalId,
       outcome: decision.outcome,
-      choice: decision.choice,
       actor: decision.actor,
       reason: decision.reason,
       decidedAt: nowISO(),

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;