yaml-flow 7.1.0 → 8.0.0

package/examples/board/source-def-handlers/copilot-source-handler.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function interpolate(template, args) {
+  return String(template).replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_m, key) => {
+    const v = args?.[key];
+    if (v === undefined) return '';
+    return typeof v === 'string' ? v : JSON.stringify(v);
+  });
+}
+
+const DEFAULT_PROMPT_CONTEXT = {
+  view_kind_guidance: [
+    'VIEW KIND GUIDANCE (for dynamic ref rendering):',
+    '- Return a _view object whenever your output data is meant for a ref element.',
+    '- Allowed _view.kind values only: table, editable-table, chart, metric, list, badge, text, narrative, markdown, form, filter, todo, alert.',
+    '- If uncertain, use "table".',
+    '- For array rows that users should edit, prefer "editable-table" and set _view.data.writeTo to a card_data path.',
+    '- For chart, set _view.data.chartType and _view.data.columns with [labelField, valueField].',
+    '- Keep _view.data minimal and valid JSON (no comments, no trailing text).',
+  ].join('\n'),
+  card_layout_guidance: [
+    'CARD LAYOUT GUIDANCE:',
+    '- Prefer compact outputs that fit a card: one primary structure plus concise rationale text.',
+    '- Avoid repeating values already present in upstream inputs.',
+    '- If you produce both machine-readable and human-readable content, keep machine-readable fields top-level and concise prose in a separate field.',
+  ].join('\n'),
+};
+
+function resolvePrompt(sourceDef, promptContext) {
+  const cfg = sourceDef?.copilot && typeof sourceDef.copilot === 'object' ? sourceDef.copilot : {};
+  const template = cfg.prompt_template ?? sourceDef.prompt_template;
+  if (!template || typeof template !== 'string') return null;
+  const args = {
+    ...(promptContext || DEFAULT_PROMPT_CONTEXT),
+    ...(sourceDef?._projections || {}),
+    ...(cfg.args || sourceDef.args || {}),
+  };
+  return interpolate(template, args);
+}
+
+function runCopilot(prompt, sourceDef, executorDir, extra) {
+  const wrapperPath = path.join(executorDir, 'scripts', 'copilot_wrapper.bat');
+  if (process.platform === 'win32' && fs.existsSync(wrapperPath)) {
+    const tmpBase = path.join(process.env.TEMP || process.cwd(), `copilot-handler-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    const outFile = `${tmpBase}.out.json`;
+    const promptFile = `${tmpBase}.prompt.txt`;
+    const sessionDir = path.join(
+      extra?.boardSetupRoot || (process.env.TEMP || process.cwd()),
+      'copilot-sessions',
+      String(sourceDef?.bindTo || 'default').replace(/[^a-zA-Z0-9_-]/g, '_'),
+    );
+    fs.mkdirSync(sessionDir, { recursive: true });
+    fs.writeFileSync(promptFile, prompt, 'utf-8');
+
+    let shapeFile = '';
+    const shape = sourceDef?.copilot?.result_shape ?? sourceDef?.result_shape;
+    if (shape && typeof shape === 'object') {
+      shapeFile = `${tmpBase}.shape.json`;
+      fs.writeFileSync(shapeFile, JSON.stringify(shape), 'utf-8');
+    }
+
+    try {
+      execFileSync('cmd.exe', [
+        '/d', '/c',
+        wrapperPath,
+        outFile,
+        sessionDir,
+        extra?.boardSetupRoot || process.cwd(),
+        `@${promptFile}`,
+        'json',
+        String(sourceDef?.bindTo || 'executor'),
+        '',
+        shapeFile,
+      ], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+      return JSON.parse(fs.readFileSync(outFile, 'utf-8').replace(/^\uFEFF/, ''));
+    } finally {
+      try { fs.unlinkSync(promptFile); } catch {}
+      try { fs.unlinkSync(outFile); } catch {}
+      if (shapeFile) { try { fs.unlinkSync(shapeFile); } catch {} }
+    }
+  }
+
+  const stdout = execFileSync('copilot', ['--allow-all'], {
+    input: prompt,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 120000,
+    cwd: extra?.boardSetupRoot || process.cwd(),
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  const firstBrace = stdout.indexOf('{');
+  const firstBracket = stdout.indexOf('[');
+  let jsonStart = -1;
+  if (firstBrace === -1) jsonStart = firstBracket;
+  else if (firstBracket === -1) jsonStart = firstBrace;
+  else jsonStart = Math.min(firstBrace, firstBracket);
+
+  if (jsonStart !== -1) {
+    try {
+      return JSON.parse(stdout.slice(jsonStart));
+    } catch {
+      return stdout;
+    }
+  }
+  return stdout;
+}
+
+export async function execute(context) {
+  const sourceDef = context?.sourceDef || {};
+  const extra = context?.extra || {};
+  const executorDir = context?.executorDir || process.cwd();
+  const promptContext = context?.promptContext || DEFAULT_PROMPT_CONTEXT;
+
+  const prompt = resolvePrompt(sourceDef, promptContext);
+  if (!prompt) {
+    return {
+      result: 'failure',
+      data: { error: 'Source definition missing copilot.prompt_template (or prompt_template)' },
+      error: 'missing prompt_template',
+    };
+  }
+
+  try {
+    const resultValue = runCopilot(prompt, sourceDef, executorDir, extra);
+    return { result: 'success', data: { resultValue } };
+  } catch (err) {
+    const msg = String(err?.message || err);
+    return { result: 'failure', data: { error: `copilot invocation failed: ${msg}` }, error: msg };
+  }
+}

package/examples/board/source-def-handlers/http-source-handler.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+const CACHE_DIR = path.join(os.tmpdir(), 'demo-executor-cache');
+const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000;
+
+function interpolate(template, args) {
+  return String(template).replace(/\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/g, (_m, key) => {
+    const v = args?.[key];
+    if (v === undefined) return '';
+    return typeof v === 'string' ? v : JSON.stringify(v);
+  });
+}
+
+function cacheKey(seed) {
+  return crypto.createHash('sha1').update(seed).digest('hex');
+}
+
+function readCache(key, ttlMs) {
+  const p = path.join(CACHE_DIR, `${key}.json`);
+  try {
+    const stat = fs.statSync(p);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs > ttlMs) return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(key, value) {
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  fs.writeFileSync(path.join(CACHE_DIR, `${key}.json`), JSON.stringify(value));
+}
+
+async function fetchJson(url, method, headers) {
+  const response = await fetch(url, { method, headers });
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = text ? JSON.parse(text) : {};
+  } catch {
+    throw new Error(`Invalid JSON from ${url}`);
+  }
+  if (!response.ok) {
+    const msg = typeof parsed?.error === 'string' ? parsed.error : `HTTP ${response.status}`;
+    throw new Error(msg);
+  }
+  return parsed;
+}
+
+async function doFetchApi(url, method, headers, ttlMs) {
+  const key = cacheKey(`url:${method}:${url}`);
+  const cached = readCache(key, ttlMs);
+  if (cached !== null) {
+    console.error(`[http-source-handler] cache hit for ${url}`);
+    return cached;
+  }
+  const data = await fetchJson(url, method, headers);
+  writeCache(key, data);
+  return data;
+}
+
+function resolveTickersArg(sourceDef, fetchArgs) {
+  const tickersFrom = sourceDef?.tickersFrom;
+  if (typeof tickersFrom !== 'string' || !tickersFrom.includes('.')) return;
+  const [refKey, fieldName] = tickersFrom.split('.', 2);
+  const arr = sourceDef?._projections?.[refKey];
+  if (!Array.isArray(arr)) return;
+  const vals = arr
+    .filter((row) => row && typeof row === 'object' && row[fieldName])
+    .map((row) => String(row[fieldName]));
+  if (vals.length > 0) fetchArgs.tickers = vals.join(',');
+}
+
+async function executeUrl(sourceDef) {
+  const cfg = sourceDef?.url;
+  if (!cfg || typeof cfg !== 'object') {
+    throw new Error('url source requires object config');
+  }
+  const method = String(cfg.method || 'GET').toUpperCase();
+  const headers = cfg.headers && typeof cfg.headers === 'object' ? cfg.headers : {};
+  const ttlMs = typeof cfg.cacheTimeout === 'number' ? cfg.cacheTimeout * 1000 : DEFAULT_CACHE_TTL_MS;
+  const fetchArgs = cfg.args && typeof cfg.args === 'object' ? { ...cfg.args } : {};
+
+  resolveTickersArg(sourceDef, fetchArgs);
+  if (sourceDef?.tickersFrom && !fetchArgs.tickers) {
+    throw new Error('url: tickersFrom resolved to empty list - skipping fetch');
+  }
+
+  const ctx = {
+    ...(sourceDef?._projections || {}),
+    ...fetchArgs,
+  };
+
+  if (typeof cfg.url !== 'string' || !cfg.url) {
+    throw new Error('url source missing url template');
+  }
+  const url = interpolate(cfg.url, ctx);
+  return doFetchApi(url, method, headers, ttlMs);
+}
+
+async function executeUrlList(sourceDef) {
+  const cfg = sourceDef?.['url-list'];
+  if (!cfg || typeof cfg !== 'object') {
+    throw new Error('url-list source requires object config');
+  }
+  const method = String(cfg.method || 'GET').toUpperCase();
+  const headers = cfg.headers && typeof cfg.headers === 'object' ? cfg.headers : {};
+  const ttlMs = typeof cfg.cacheTimeout === 'number' ? cfg.cacheTimeout * 1000 : DEFAULT_CACHE_TTL_MS;
+
+  const urlList = sourceDef?._projections?.url_list;
+  if (!Array.isArray(urlList) || urlList.length === 0) {
+    throw new Error('url-list source requires _projections.url_list as non-empty array');
+  }
+
+  const results = [];
+  for (const u of urlList) {
+    results.push(await doFetchApi(String(u), method, headers, ttlMs));
+  }
+  return results;
+}
+
+export async function execute(context) {
+  const kind = context?.kind;
+  const sourceDef = context?.sourceDef || {};
+  try {
+    let resultValue;
+    if (kind === 'url') {
+      resultValue = await executeUrl(sourceDef);
+    } else if (kind === 'url-list') {
+      resultValue = await executeUrlList(sourceDef);
+    } else {
+      throw new Error(`http-source-handler does not support kind: ${kind}`);
+    }
+    return { result: 'success', data: { resultValue } };
+  } catch (err) {
+    const msg = String(err?.message || err);
+    return { result: 'failure', data: { error: msg }, error: msg };
+  }
+}

package/examples/board/source_def_flows.json

@@ -0,0 +1,249 @@
+{
+  "version": "1.0",
+  "description": "Self-contained source-def registry for demo-task-executor runtimes.",
+  "executor": "demo-task-executor",
+  "subcommands": [
+    "run-source-fetch",
+    "describe-capabilities",
+    "validate-source-def",
+    "validate-card-preflight",
+    "probe-source-preflight"
+  ],
+  "extraSchema": {
+    "description": "Board topology context passed via --extra (base64-encoded JSON, baked at init).",
+    "properties": {
+      "boardSetupRoot": {
+        "type": "string",
+        "description": "Absolute path to board root."
+      },
+      "boardId": {
+        "type": "string",
+        "description": "Board identifier."
+      },
+      "boardRuntimeDir": {
+        "type": "string",
+        "description": "Relative path to runtime dir."
+      },
+      "runtimeStatusDir": {
+        "type": "string",
+        "description": "Relative path to runtime-out dir."
+      },
+      "cardsDir": {
+        "type": "string",
+        "description": "Relative path to cards dir."
+      },
+      "serverUrl": {
+        "type": "string",
+        "description": "Base URL of the hosting server (e.g. http://127.0.0.1:7799). Used by source kinds that call server-side proxy endpoints."
+      },
+      "boardLiveCardsCliJs": {
+        "type": "string",
+        "description": "Absolute path to board-live-cards-cli.js when configured by the runtime."
+      },
+      "stepMachineCliPath": {
+        "type": "string",
+        "description": "Absolute path to step-machine-cli.js when configured by the runtime."
+      }
+    }
+  },
+  "kinds": {
+    "url": {
+      "detect": {
+        "field": "url"
+      },
+      "flow": "./source-def-flows/url.flow.json",
+      "validate": [
+        {
+          "field": "url",
+          "type": "object",
+          "message": "url must be an object."
+        },
+        {
+          "field": "url.url",
+          "type": "string",
+          "message": "url.url is required and must be a string."
+        }
+      ],
+      "probe": {
+        "strategy": "http-head",
+        "urlFrom": "url.url"
+      },
+      "manifest": {
+        "description": "Single URL fetch via curl with interpolation and cache.",
+        "inputSchema": {
+          "url": {
+            "type": "object",
+            "required": true,
+            "properties": {
+              "url": {
+                "type": "string",
+                "required": true
+              },
+              "method": {
+                "type": "string",
+                "required": false
+              },
+              "headers": {
+                "type": "object",
+                "required": false
+              },
+              "args": {
+                "type": "object",
+                "required": false
+              },
+              "cacheTimeout": {
+                "type": "number",
+                "required": false
+              }
+            }
+          },
+          "tickersFrom": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    "url-list": {
+      "detect": {
+        "field": "url-list"
+      },
+      "flow": "./source-def-flows/url-list.flow.json",
+      "validate": [
+        {
+          "field": "url-list",
+          "type": "object",
+          "message": "url-list must be an object."
+        }
+      ],
+      "probe": {
+        "strategy": "http-head",
+        "urlFrom": "_projections.url_list[0]"
+      },
+      "manifest": {
+        "description": "Fan-out URL fetch over _projections.url_list.",
+        "inputSchema": {
+          "url-list": {
+            "type": "object",
+            "required": true,
+            "properties": {
+              "method": {
+                "type": "string",
+                "required": false
+              },
+              "headers": {
+                "type": "object",
+                "required": false
+              },
+              "cacheTimeout": {
+                "type": "number",
+                "required": false
+              }
+            }
+          }
+        }
+      }
+    },
+    "copilot": {
+      "detect": {
+        "anyOfFields": [
+          "copilot",
+          "prompt_template"
+        ]
+      },
+      "flow": "./source-def-flows/copilot.flow.json",
+      "validate": [
+        {
+          "condition": "copilot-or-prompt",
+          "message": "copilot must be an object, or prompt_template must be a top-level string."
+        }
+      ],
+      "probe": {
+        "strategy": "command-check",
+        "command": "copilot",
+        "args": [
+          "--version"
+        ]
+      },
+      "manifest": {
+        "description": "Invoke Copilot with prompt interpolation.",
+        "inputSchema": {
+          "copilot": {
+            "type": "object",
+            "required": false
+          },
+          "prompt_template": {
+            "type": "string",
+            "required": false
+          }
+        }
+      }
+    },
+    "workiq": {
+      "detect": {
+        "field": "workiq"
+      },
+      "flow": "./source-def-flows/workiq.flow.json",
+      "validate": [
+        {
+          "field": "workiq",
+          "type": "object",
+          "message": "workiq must be an object."
+        },
+        {
+          "field": "workiq.query_template",
+          "type": "string",
+          "message": "workiq.query_template is required and must be a string."
+        }
+      ],
+      "probe": {
+        "strategy": "command-check",
+        "command": "workiq",
+        "args": [
+          "--version"
+        ]
+      },
+      "manifest": {
+        "description": "Invoke WorkIQ via demo-server HTTP proxy endpoint.",
+        "inputSchema": {
+          "workiq": {
+            "type": "object",
+            "required": true
+          }
+        }
+      }
+    },
+    "mock": {
+      "detect": {
+        "field": "mock"
+      },
+      "flow": "./source-def-flows/mock.flow.json",
+      "validate": [
+        {
+          "field": "mock",
+          "type": "string",
+          "message": "mock must be a string key."
+        }
+      ],
+      "probe": {
+        "strategy": "mock-db-lookup"
+      },
+      "manifest": {
+        "description": "Look up values from demo MOCK_DB map.",
+        "inputSchema": {
+          "mock": {
+            "type": "string",
+            "required": true
+          }
+        }
+      }
+    }
+  },
+  "resolveOrder": [
+    "url",
+    "url-list",
+    "copilot",
+    "workiq",
+    "mock"
+  ]
+}