@tagma/sdk 0.2.4 → 0.2.6

package/src/logger.ts

@@ -1,112 +1,164 @@
-import { resolve, dirname } from 'node:path';
-import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
-
-/**
- * Dual-channel logger.
- *
- *   - `info/warn/error` → console AND file (brief, user-visible events)
- *   - `debug`           → file ONLY (verbose diagnostics)
- *   - `section`         → file ONLY (visual separators)
- *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
- *
- * Log file path: <workDir>/.tagma/logs/<runId>/pipeline.log (one file per pipeline run,
- * truncated on construction).
- */
-export class Logger {
-  private readonly filePath: string;
-  private readonly runDir: string;
-
-  constructor(workDir: string, runId: string) {
-    this.runDir = resolve(workDir, '.tagma', 'logs', runId);
-    this.filePath = resolve(this.runDir, 'pipeline.log');
-    mkdirSync(dirname(this.filePath), { recursive: true });
-    writeFileSync(
-      this.filePath,
-      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
-      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
-      `# Work dir: ${workDir}\n\n`,
-    );
-  }
-
-  info(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} ${message}`;
-    console.log(line);
-    this.append(line);
-  }
-
-  warn(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} WARN: ${message}`;
-    console.warn(line);
-    this.append(line);
-  }
-
-  error(prefix: string, message: string): void {
-    const line = `${timestamp()} ${prefix} ERROR: ${message}`;
-    console.error(line);
-    this.append(line);
-  }
-
-  /** File-only diagnostic log line. */
-  debug(prefix: string, message: string): void {
-    this.append(`${timestamp()} ${prefix} DEBUG: ${message}`);
-  }
-
-  /** File-only visual separator with title. */
-  section(title: string): void {
-    this.append(`\n━━━ ${title} ━━━`);
-  }
-
-  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
-  quiet(message: string): void {
-    this.append(message);
-  }
-
-  private append(line: string): void {
-    try {
-      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
-    } catch {
-      // Swallow log write failures; engine correctness shouldn't depend on logging.
-    }
-  }
-
-  get path(): string {
-    return this.filePath;
-  }
-
-  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
-  get dir(): string {
-    return this.runDir;
-  }
-}
-
-function timestamp(): string {
-  const d = new Date();
-  const hh = String(d.getHours()).padStart(2, '0');
-  const mm = String(d.getMinutes()).padStart(2, '0');
-  const ss = String(d.getSeconds()).padStart(2, '0');
-  const ms = String(d.getMilliseconds()).padStart(3, '0');
-  return `${hh}:${mm}:${ss}.${ms}`;
-}
-
-/** Return the last `n` non-empty lines of `text`, joined with newlines. */
-export function tailLines(text: string, n: number): string {
-  if (!text) return '';
-  const lines = text.split(/\r?\n/).filter(l => l.length > 0);
-  return lines.slice(-n).join('\n');
-}
-
-/**
- * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
- * appending a marker when truncation occurred.
- * Uses TextEncoder so CJK and emoji (multi-byte) characters are counted correctly.
- */
-export function clip(text: string, maxBytes = 16 * 1024): string {
-  if (!text) return '';
-  const encoder = new TextEncoder();
-  const bytes = encoder.encode(text);
-  if (bytes.length <= maxBytes) return text;
-  const omittedBytes = bytes.length - maxBytes;
-  // TextDecoder handles partial code-point boundaries safely (replacement char insertion)
-  const truncated = new TextDecoder().decode(bytes.slice(0, maxBytes));
-  return truncated + `\n…[truncated ${omittedBytes} bytes]`;
-}
+import { resolve, dirname } from 'node:path';
+import { mkdirSync, appendFileSync, writeFileSync } from 'node:fs';
+
+/**
+ * Structured record emitted for every log line. Consumers (e.g. the editor
+ * server) use this to stream process-level detail into UIs alongside the
+ * on-disk pipeline.log. `taskId` is extracted from a `[task:<id>]` prefix
+ * when the call site passes one, or overridden explicitly via the optional
+ * `taskId` argument on `section`/`quiet` (which carry no prefix).
+ */
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'section' | 'quiet';
+
+export interface LogRecord {
+  readonly level: LogLevel;
+  readonly taskId: string | null;
+  readonly timestamp: string;
+  readonly text: string;
+}
+
+export type LogListener = (record: LogRecord) => void;
+
+const TASK_PREFIX_RE = /\[task:([^\]]+)\]/;
+
+function taskIdFromPrefix(prefix: string): string | null {
+  const m = TASK_PREFIX_RE.exec(prefix);
+  return m ? m[1] : null;
+}
+
+/**
+ * Dual-channel logger.
+ *
+ *   - `info/warn/error` → console AND file (brief, user-visible events)
+ *   - `debug`           → file ONLY (verbose diagnostics)
+ *   - `section`         → file ONLY (visual separators)
+ *   - `quiet`           → file ONLY (bulk payload like full stdout dumps)
+ *
+ * Log file path: <workDir>/.tagma/logs/<runId>/pipeline.log (one file per pipeline run,
+ * truncated on construction). Every line is also forwarded to the optional
+ * `onLine` callback as a structured `LogRecord`, so callers that want to
+ * stream the run process over IPC/SSE don't need to tail the file.
+ */
+export class Logger {
+  private readonly filePath: string;
+  private readonly runDir: string;
+  private readonly onLine: LogListener | null;
+
+  constructor(workDir: string, runId: string, onLine?: LogListener) {
+    this.runDir = resolve(workDir, '.tagma', 'logs', runId);
+    this.filePath = resolve(this.runDir, 'pipeline.log');
+    this.onLine = onLine ?? null;
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(
+      this.filePath,
+      `# Pipeline run ${runId} @ ${new Date().toISOString()}\n` +
+      `# Host: ${process.platform} ${process.arch}  Bun: ${process.versions.bun ?? 'n/a'}\n` +
+      `# Work dir: ${workDir}\n\n`,
+    );
+  }
+
+  info(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} ${message}`;
+    console.log(line);
+    this.emit('info', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  warn(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} WARN: ${message}`;
+    console.warn(line);
+    this.emit('warn', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  error(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} ERROR: ${message}`;
+    console.error(line);
+    this.emit('error', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  /** File-only diagnostic log line. */
+  debug(prefix: string, message: string): void {
+    const ts = timestamp();
+    const line = `${ts} ${prefix} DEBUG: ${message}`;
+    this.emit('debug', ts, line, taskIdFromPrefix(prefix));
+    this.append(line);
+  }
+
+  /** File-only visual separator with title. */
+  section(title: string, taskId?: string | null): void {
+    const ts = timestamp();
+    const text = `\n━━━ ${title} ━━━`;
+    this.emit('section', ts, text, taskId ?? null);
+    this.append(text);
+  }
+
+  /** File-only bulk payload (e.g. full stdout / stderr dumps). */
+  quiet(message: string, taskId?: string | null): void {
+    const ts = timestamp();
+    this.emit('quiet', ts, message, taskId ?? null);
+    this.append(message);
+  }
+
+  private append(line: string): void {
+    try {
+      appendFileSync(this.filePath, line.endsWith('\n') ? line : line + '\n');
+    } catch {
+      // Swallow log write failures; engine correctness shouldn't depend on logging.
+    }
+  }
+
+  private emit(level: LogLevel, ts: string, text: string, taskId: string | null): void {
+    if (!this.onLine) return;
+    try {
+      this.onLine({ level, taskId, timestamp: ts, text });
+    } catch {
+      // Never let a listener error derail the pipeline.
+    }
+  }
+
+  get path(): string {
+    return this.filePath;
+  }
+
+  /** Directory that holds all artifacts for this run (pipeline.log, *.stderr, etc.). */
+  get dir(): string {
+    return this.runDir;
+  }
+}
+
+function timestamp(): string {
+  const d = new Date();
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mm = String(d.getMinutes()).padStart(2, '0');
+  const ss = String(d.getSeconds()).padStart(2, '0');
+  const ms = String(d.getMilliseconds()).padStart(3, '0');
+  return `${hh}:${mm}:${ss}.${ms}`;
+}
+
+/** Return the last `n` non-empty lines of `text`, joined with newlines. */
+export function tailLines(text: string, n: number): string {
+  if (!text) return '';
+  const lines = text.split(/\r?\n/).filter(l => l.length > 0);
+  return lines.slice(-n).join('\n');
+}
+
+/**
+ * Truncate a blob to at most `maxBytes` UTF-8 bytes for log embedding,
+ * appending a marker when truncation occurred.
+ * Uses TextEncoder so CJK and emoji (multi-byte) characters are counted correctly.
+ */
+export function clip(text: string, maxBytes = 16 * 1024): string {
+  if (!text) return '';
+  const encoder = new TextEncoder();
+  const bytes = encoder.encode(text);
+  if (bytes.length <= maxBytes) return text;
+  const omittedBytes = bytes.length - maxBytes;
+  // TextDecoder handles partial code-point boundaries safely (replacement char insertion)
+  const truncated = new TextDecoder().decode(bytes.slice(0, maxBytes));
+  return truncated + `\n…[truncated ${omittedBytes} bytes]`;
+}

package/src/middlewares/static-context.ts

@@ -4,6 +4,22 @@ 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,

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';
@@ -59,6 +63,7 @@ export type { WebSocketApprovalAdapter, WebSocketApprovalAdapterOptions } from '
 
 // ── Logger ──
 export { Logger, tailLines, clip } from './logger';
+export type { LogRecord, LogLevel, LogListener } from './logger';
 
 // ── Hook context types (useful for frontend display) ──
 export type { HookResult, PipelineInfo, TrackInfo, TaskInfo } from './hooks';

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,72 @@
-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',
+      },
+    },
+  },
+
+  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 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,
+      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, 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'}`);
+    }
+  },
+};