@nexusbloom/cli 0.3.4 → 0.8.0

package/src/ui.js

@@ -19,6 +19,18 @@ import {
 
 export const PAGE_SIZE = 20;
 
+/**
+ * True when it is safe to open an interactive prompt.
+ *
+ * Prompts must never be attempted when stdout/stdin is piped or run under CI —
+ * inquirer would either hang forever or throw. Any list long enough to page
+ * through should degrade to a plain, searchable dump instead.
+ */
+export function isInteractive() {
+  if (process.env.NXB_NO_INTERACTIVE || process.env.CI) return false;
+  return Boolean(process.stdout.isTTY && process.stdin.isTTY);
+}
+
 // ─── Simple helpers ──────────────────────────────────────────────────────────
 
 /**
@@ -116,6 +128,9 @@ export function paginate(items, pageSize = PAGE_SIZE, currentPage = 1) {
 /**
  * Interactive paginator: renders via `renderPage`, offers prev/next/done/cancel.
  * Returns the last page result or null on cancel.
+ *
+ * When the terminal is not interactive (piped output, CI), it renders the
+ * first page once and returns instead of opening a prompt.
  */
 export async function paginateInteractive(
   items,
@@ -132,6 +147,11 @@ export async function paginateInteractive(
   let page = 1;
   let result = paginate(all, pageSize, page);
 
+  if (options.interactive === false || !isInteractive()) {
+    renderPage(result);
+    return result;
+  }
+
   while (true) {
     renderPage(result);
 

package/src/values.js

@@ -0,0 +1,260 @@
+/**
+ * values.js — Value paths and pure transforms for pipelines.
+ *
+ * Two jobs:
+ *   1. Address values inside a tool's output: `total_words`, `data[0].email`,
+ *      and `$` for the whole object. Arrays are unavoidable — `data-generator`
+ *      returns `data: array`, so the next step needs an index.
+ *   2. Convert between shapes without needing a separate tool: `$text|len`,
+ *      `$max|int`, `$data|first`.
+ *
+ * Every transform is pure and synchronous, which is what makes the wiring plan
+ * checkable before anything runs.
+ */
+
+/** Distinguishes "the field is absent" from "the field holds undefined". */
+export const MISSING = Symbol("missing");
+
+/**
+ * Parse a path expression into segments.
+ *
+ *   ""  / "$"     → []            (the whole value)
+ *   "total_words" → ["total_words"]
+ *   "data[0]"     → ["data", 0]
+ *   "a.b[2].c"    → ["a", "b", 2, "c"]
+ *
+ * @throws {Error} on malformed paths
+ */
+export function parsePath(path) {
+  if (path == null) return [];
+  const raw = String(path).trim();
+  if (!raw || raw === "$" || raw === ".") return [];
+
+  const segments = [];
+  let i = 0;
+  // A leading identifier segment.
+  while (i < raw.length) {
+    const c = raw[i];
+    if (c === ".") {
+      i++;
+      continue;
+    }
+    if (c === "[") {
+      const close = raw.indexOf("]", i);
+      if (close === -1) throw new Error(`Unclosed "[" in path "${raw}"`);
+      const inner = raw.slice(i + 1, close).trim();
+      if (/^\d+$/.test(inner)) segments.push(Number(inner));
+      else if (/^["'].*["']$/.test(inner)) segments.push(inner.slice(1, -1));
+      else throw new Error(`Invalid index "[${inner}]" in path "${raw}"`);
+      i = close + 1;
+      continue;
+    }
+    let j = i;
+    while (j < raw.length && raw[j] !== "." && raw[j] !== "[") j++;
+    const key = raw.slice(i, j);
+    if (!key) throw new Error(`Empty segment in path "${raw}"`);
+    segments.push(key);
+    i = j;
+  }
+  return segments;
+}
+
+/**
+ * Read a path out of a value.
+ * @returns {value|typeof MISSING}
+ */
+export function getPath(root, path) {
+  const segments = Array.isArray(path) ? path : parsePath(path);
+  if (segments.length === 0) return root;
+
+  let cur = root;
+  for (const seg of segments) {
+    if (cur === null || cur === undefined) return MISSING;
+    if (Array.isArray(cur)) {
+      const idx = typeof seg === "number" ? seg : Number(seg);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= cur.length) return MISSING;
+      cur = cur[idx];
+    } else if (typeof cur === "object") {
+      if (!Object.prototype.hasOwnProperty.call(cur, seg)) return MISSING;
+      cur = cur[seg];
+    } else {
+      return MISSING;
+    }
+  }
+  return cur === undefined ? MISSING : cur;
+}
+
+/** Render a path back to its `$`-prefixed source form. */
+export function formatPath(segments) {
+  const arr = Array.isArray(segments) ? segments : parsePath(segments);
+  if (!arr.length) return "$";
+  let out = "";
+  for (const seg of arr) {
+    if (typeof seg === "number") out += `[${seg}]`;
+    else out += out ? `.${seg}` : seg;
+  }
+  return out;
+}
+
+// ─── Coercion helpers ────────────────────────────────────────────────────────
+
+const toStr = (v) => {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "string") return v;
+  if (typeof v === "object") return JSON.stringify(v);
+  return String(v);
+};
+
+const asNumber = (v) => {
+  if (typeof v === "number") return v;
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (typeof v === "string") {
+    const n = Number(v.trim());
+    return Number.isNaN(n) ? MISSING : n;
+  }
+  return MISSING;
+};
+
+/**
+ * Transform library.
+ *
+ * Each entry is `(value, ...args) => value`. Throwing is allowed — pipe.js
+ * turns a throw into a connection-level error naming the transform.
+ *
+ * `needsArg` marks transforms that are meaningless without an argument, so
+ * `$x|slice` can be reported at plan time rather than silently.
+ */
+export const TRANSFORMS = {
+  // — shape —
+  len: (v) => (typeof v === "string" || Array.isArray(v) ? v.length : v && typeof v === "object" ? Object.keys(v).length : 0),
+  // Alias of `len`. A count *of what* would need an argument; this one does not
+  // take one, and silently ignoring an argument is how `$text|count("a")` would
+  // quietly return the string length instead of the number of matches.
+  count: (v) => TRANSFORMS.len(v),
+  words: (v) => (toStr(v).trim() ? toStr(v).trim().split(/\s+/).length : 0),
+  lines: (v) => (toStr(v) === "" ? 0 : toStr(v).split(/\r?\n/).length),
+  chars: (v) => toStr(v).length,
+
+  // Absence must be MISSING, never raw `undefined`: `default()` and the
+  // runtime's missing-value check both compare against MISSING, so returning
+  // undefined would slip past a fallback the user explicitly asked for.
+  first: (v) => (Array.isArray(v) ? (v.length ? v[0] : MISSING) : v),
+  last: (v) => (Array.isArray(v) ? (v.length ? v[v.length - 1] : MISSING) : v),
+  get: (v, i) => {
+    if (!Array.isArray(v)) return v;
+    const n = Number(i);
+    if (!Number.isInteger(n) || n < 0 || n >= v.length) return MISSING;
+    return v[n];
+  },
+  slice: (v, a, b) => (Array.isArray(v) || typeof v === "string" ? v.slice(Number(a), b == null ? undefined : Number(b)) : v),
+  join: (v, sep = ",") => (Array.isArray(v) ? v.join(sep) : toStr(v)),
+  keys: (v) => (v && typeof v === "object" ? Object.keys(v) : []),
+  values: (v) => (v && typeof v === "object" ? Object.values(v) : []),
+  reverse: (v) => (Array.isArray(v) ? [...v].reverse() : v),
+  sort: (v, key) => {
+    if (!Array.isArray(v)) return v;
+    const copy = [...v];
+    copy.sort((a, b) => {
+      const av = key ? getPath(a, key) : a;
+      const bv = key ? getPath(b, key) : b;
+      if (av === bv) return 0;
+      if (av === MISSING) return 1;
+      if (bv === MISSING) return -1;
+      return av < bv ? -1 : 1;
+    });
+    return copy;
+  },
+
+  // — text —
+  upper: (v) => toStr(v).toUpperCase(),
+  lower: (v) => toStr(v).toLowerCase(),
+  trim: (v) => toStr(v).trim(),
+  replace: (v, a, b) => toStr(v).split(a).join(b ?? ""),
+  pad: (v, n, c = " ") => toStr(v).padStart(Number(n), c),
+  split: (v, sep) => toStr(v).split(sep),
+
+  // — type coercion —
+  str: (v) => toStr(v),
+  int: (v) => {
+    const n = asNumber(v);
+    if (n === MISSING) return MISSING;
+    return Math.trunc(n);
+  },
+  float: (v) => asNumber(v),
+  num: (v) => asNumber(v),
+  bool: (v) => {
+    if (typeof v === "boolean") return v;
+    const s = toStr(v).trim().toLowerCase();
+    if (["true", "1", "yes", "y", "on"].includes(s)) return true;
+    if (["false", "0", "no", "n", "off", ""].includes(s)) return false;
+    return MISSING;
+  },
+
+  // — structure —
+  json: (v) => toStr(v),
+  unjson: (v) => {
+    try {
+      return JSON.parse(toStr(v));
+    } catch {
+      return MISSING;
+    }
+  },
+  pick: (v, key) => {
+    const r = getPath(v, key);
+    return r;
+  },
+  default: (v, fallback) => (v === MISSING || v === undefined || v === null || v === "" ? fallback : v),
+};
+
+/** Transforms that are no-ops on their argument order, used for plan hints. */
+export const TRANSFORM_ARITY = {
+  get: 2,
+  slice: 3,
+  join: 2,
+  split: 2,
+  replace: 3,
+  pad: 3,
+  sort: 2,
+  pick: 2,
+  default: 2,
+};
+
+export function transformNames() {
+  return Object.keys(TRANSFORMS).sort();
+}
+
+/**
+ * Apply a chain of transforms to a value.
+ * @param {any} value
+ * @param {Array<{name: string, args: any[]}>} chain
+ * @returns {any|typeof MISSING}
+ */
+export function applyTransforms(value, chain) {
+  let cur = value;
+  for (const step of chain) {
+    const fn = TRANSFORMS[step.name];
+    if (!fn) throw new Error(`Unknown transform "${step.name}". Run \`nxb pipe --transforms\`.`);
+    // A missing value stays missing unless the transform can supply one —
+    // only `default()` is allowed to invent a value.
+    if (cur === MISSING && step.name !== "default") return MISSING;
+    // A step may legitimately take no argument; treat a missing `args` as
+    // empty rather than failing to iterate undefined.
+    cur = fn(cur, ...(step.args || []));
+    if (cur === MISSING) return MISSING;
+  }
+  return cur;
+}
+
+/** Short, safe preview of a value for the wiring table. */
+export function preview(value, max = 28) {
+  if (value === MISSING) return "";
+  if (value === null) return "null";
+  if (typeof value === "string") {
+    const one = value.replace(/\s+/g, " ");
+    return `"${one.length > max ? `${one.slice(0, max)}…` : one}"`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `[${value.length}]`;
+  if (typeof value === "object") return `{${Object.keys(value).length}}`;
+  return String(value);
+}

package/src/wizard.js

@@ -0,0 +1,349 @@
+/**
+ * wizard.js — Interactive pipeline builder.
+ *
+ * The design point: wires are made against a tool's *real* output, not its
+ * declared `output_schema`. Run the tool, inspect what actually came back —
+ * including fields the schema never mentioned — and only then choose what to
+ * send onward. A browser node builder cannot do this without executing the
+ * tool, which is exactly why this belongs in the CLI.
+ *
+ * The wizard is stateless: render, prompt, act, render. Nothing is redrawn
+ * while a prompt is open, because @inquirer/core cannot update a live prompt.
+ * That keeps it safe over SSH and leaves every step in the scrollback.
+ */
+
+import chalk from "chalk";
+import * as inquirer from "@inquirer/prompts";
+
+/**
+ * Every prompt goes through this bundle so the wizard's decision logic can be
+ * driven by tests without a terminal. Rendering stays in @inquirer; what is
+ * worth testing is which question gets asked and what it does with the answer.
+ */
+export const defaultPrompts = {
+  search: inquirer.search,
+  select: inquirer.select,
+  input: inquirer.input,
+  number: inquirer.number,
+  confirm: inquirer.confirm,
+};
+
+import { fetchTools, rankTools } from "./tools.js";
+import { execInSandbox } from "./sandbox.js";
+import { configGet } from "./tools.js";
+import { runRemote } from "./run.js";
+import { inferType, schemaTypes, typeLabel, compatibility } from "./types.js";
+import { formatPath, parsePath, preview, transformNames } from "./values.js";
+import { isInteractive } from "./ui.js";
+import { renderHeader } from "./ui.js";
+
+// ─── Execution ───────────────────────────────────────────────────────────────
+
+async function loadTool(slug) {
+  const { fetchToolSource } = await import("./tools.js");
+  return fetchToolSource(slug);
+}
+
+async function runOnce(slug, input) {
+  const info = await loadTool(slug);
+  if (!info?.manifest) return { ok: false, error: `Tool "${slug}" not found.` };
+
+  const { manifest, coreLogicSource } = info;
+  const apiKey = process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
+
+  if (!coreLogicSource && apiKey) {
+    const res = await runRemote(slug, input, { apiKey, jsonMode: false, quiet: true });
+    return res?.ok ? { ok: true, result: res.result } : { ok: false, error: res?.error || "remote failed" };
+  }
+  if (!coreLogicSource) {
+    return { ok: false, error: `"${slug}" has no runnable source. Set an API key or use --local.` };
+  }
+  return execInSandbox({ source: coreLogicSource, input, timeoutMs: manifest.timeout_ms || 5000 });
+}
+
+// ─── Output introspection ────────────────────────────────────────────────────
+
+/** Flat list of leaf fields in a tool's actual output, with runtime types. */
+export function describeOutputFields(value, prefix = [], depth = 0) {
+  const fields = [];
+  if (value === null || typeof value !== "object" || Array.isArray(value) || depth > 2) {
+    if (prefix.length) fields.push({ path: prefix, value });
+    return fields;
+  }
+  for (const [k, v] of Object.entries(value)) {
+    const path = [...prefix, k];
+    if (v !== null && typeof v === "object" && !Array.isArray(v) && depth < 2) {
+      fields.push(...describeOutputFields(v, path, depth + 1));
+    } else {
+      fields.push({ path, value: v });
+    }
+  }
+  return fields;
+}
+
+/** Render the observed output so the user can read it before wiring. */
+function renderObservedOutput(fields) {
+  if (!fields.length) {
+    console.log(chalk.yellow("    (the tool returned nothing to pass on)"));
+    return;
+  }
+  const width = Math.max(...fields.map((f) => formatPath(f.path).length));
+  for (const f of fields) {
+    const path = formatPath(f.path).padEnd(width);
+    console.log(`      ${chalk.cyan(path)}  ${chalk.gray(inferType(f.value).padEnd(8))} ${chalk.dim(preview(f.value, 34))}`);
+  }
+}
+
+// ─── Prompts ─────────────────────────────────────────────────────────────────
+
+async function pickTool(tools, exclude = [], P = defaultPrompts) {
+  const pool = tools.filter((t) => !exclude.includes(t.slug));
+  const source = async (term) => {
+    const hits = term ? rankTools(pool, term) : pool;
+    return hits.slice(0, 50).map((t) => ({
+      value: t,
+      name: `${t.icon || "🔧"}  ${(t.slug || "").padEnd(28)} ${t.short_description || t.description || ""}`,
+    }));
+  };
+  return P.search({ message: "Tool", source, pageSize: 15 });
+}
+
+/** Prompt for one literal input, honouring the declared type. */
+async function promptLiteral(field, prop, P = defaultPrompts) {
+  const types = schemaTypes(prop);
+  if (Array.isArray(prop?.enum) && prop.enum.length) {
+    return P.select({
+      message: `${field}  ${chalk.gray(typeLabel(types) + " (enum)")}`,
+      choices: [
+        ...(prop.default !== undefined ? [{ name: chalk.gray(`default: ${prop.default}`), value: prop.default }] : []),
+        ...prop.enum.map((v) => ({ name: String(v), value: v })),
+      ],
+    });
+  }
+  if (types.includes("boolean")) {
+    return P.confirm({ message: `${field}  ${chalk.gray("boolean")}`, default: prop.default ?? true });
+  }
+  if (types.includes("integer") || types.includes("number")) {
+    const min = types.includes("integer") ? Math.ceil(prop?.minimum ?? -Infinity) : prop?.minimum;
+    const max = types.includes("integer") ? Math.floor(prop?.maximum ?? Infinity) : prop?.maximum;
+    return P.number({
+      message: `${field}  ${chalk.gray(typeLabel(types))}`,
+      ...(min != null && Number.isFinite(min) ? { min } : {}),
+      ...(max != null && Number.isFinite(max) ? { max } : {}),
+      ...(prop?.default !== undefined ? { default: prop.default } : {}),
+    });
+  }
+  const answer = await P.input({
+    message: `${field}  ${chalk.gray(typeLabel(types))}`,
+    ...(prop?.default !== undefined ? { default: String(prop.default) } : {}),
+    ...(prop?.description ? { description: undefined } : {}),
+  });
+  return answer === "" && prop?.default !== undefined ? prop.default : answer;
+}
+
+/**
+ * Ask how each input field of the next tool is supplied: wired from the
+ * previous output, or a literal.
+ */
+async function wireFields(manifest, prevSlug, prevFields, P = defaultPrompts) {
+  const props = manifest.input_schema?.properties || {};
+  const required = new Set(manifest.input_schema?.required || []);
+  const assignments = [];
+
+  for (const [field, prop] of Object.entries(props)) {
+    const targetTypes = schemaTypes(prop);
+    const canSkip = !required.has(field);
+
+    const choices = [
+      {
+        name: chalk.gray("· set by hand"),
+        value: { kind: "literal" },
+      },
+      ...prevFields.map((f) => {
+        const path = formatPath(f.path);
+        const from = inferType(f.value);
+        const compat = targetTypes.length ? compatibility(from, targetTypes) : { level: "ok" };
+        const flag =
+          compat.level === "cast" ? chalk.red(" · needs a transform")
+          : compat.level === "lossy" ? chalk.yellow(" · lossy")
+          : compat.level === "invalid" ? chalk.red(" · type mismatch")
+          : "";
+        return {
+          name: `${chalk.cyan(path.padEnd(24))} ${chalk.gray(from.padEnd(8))} ${chalk.dim(preview(f.value, 24))}${flag}`,
+          value: { kind: "wire", path },
+        };
+      }),
+      ...(canSkip ? [{ name: chalk.gray("· leave empty"), value: { kind: "skip" } }] : []),
+    ];
+
+    const choice = await P.select({
+      message: `${prevSlug} → ${chalk.cyan(field)}  ${chalk.gray(typeLabel(targetTypes))}${required.has(field) ? chalk.red(" *") : ""}`,
+      choices,
+      pageSize: 14,
+    });
+
+    if (choice.kind === "skip") continue;
+
+    if (choice.kind === "literal") {
+      const value = await promptLiteral(field, prop, P);
+      assignments.push({ kind: "literal", text: `${field}=${formatLiteral(value)}` });
+      continue;
+    }
+
+    // A transform was flagged as necessary — offer the suggestion inline.
+    const source = prevFields.find((f) => formatPath(f.path) === choice.path);
+    const from = source ? inferType(source.value) : "unknown";
+    const compat = targetTypes.length ? compatibility(from, targetTypes) : { level: "ok" };
+    let transform = "";
+
+    if (compat.level === "cast" && compat.suggestion) {
+      const use = await P.confirm({
+        message: `${field} expects ${typeLabel(targetTypes)} — apply ${chalk.cyan(compat.suggestion)}?`,
+        default: true,
+      });
+      if (use) transform = `|${compat.suggestion}`;
+    }
+
+    assignments.push({ kind: "wire", text: `${field}=$${choice.path}${transform}` });
+  }
+
+  return assignments;
+}
+
+function formatLiteral(value) {
+  if (typeof value === "string" && value !== "" && !/^[\w.@/+-]+$/.test(value)) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string" && value === "") return '""';
+  return String(value);
+}
+
+// ─── Wizard ──────────────────────────────────────────────────────────────────
+
+/**
+ * Build a pipeline interactively.
+ * @returns {Promise<{ok: boolean, spec?: string}>}
+ */
+export async function buildWizard(opts = {}) {
+  const P = opts.prompts || defaultPrompts;
+  const listTools = opts.fetchTools || fetchTools;
+  const getTool = opts.loadTool || loadTool;
+  const execute = opts.runOnce || runOnce;
+  // Tests drive a non-TTY session; production does not.
+  if (opts.interactive === undefined ? !isInteractive() : !opts.interactive) {
+    console.log(chalk.yellow("\n  The pipeline builder needs an interactive terminal."));
+    console.log(chalk.dim("  For scripted or piped use:\n"));
+    console.log(chalk.dim('    nxb pipe \'tool-a x=@in | tool-b count=$total|len\'\n'));
+    return { ok: false };
+  }
+
+  const tools = await listTools();
+  if (!tools || !tools.length) {
+    console.log(chalk.yellow("  No tools available. Check your connection, or run `nxb list --refresh`."));
+    return { ok: false };
+  }
+
+  const steps = [];
+  const outputs = [];
+  const usedSlugs = [];
+
+  for (;;) {
+    renderHeader(
+      steps.length ? `Step ${steps.length + 1}` : "Build a pipeline",
+      { subtitle: steps.length ? "Pick the next tool to feed" : "Start with any tool" }
+    );
+
+    const tool = await pickTool(tools, usedSlugs, P);
+    if (!tool) break;
+
+    const info = await getTool(tool.slug);
+    const manifest = info?.manifest;
+    if (!manifest) {
+      console.log(chalk.yellow(`  "${tool.slug}" has no manifest — skipping.`));
+      continue;
+    }
+
+    // Wire from the previous step, if there is one.
+    let assignments = [];
+    if (outputs.length) {
+      const prev = outputs[outputs.length - 1];
+      assignments = await wireFields(manifest, prev.slug, prev.fields, P);
+    } else {
+      // First step: ask for each field by hand.
+      const props = manifest.input_schema?.properties || {};
+      for (const [field, prop] of Object.entries(props)) {
+        const value = await promptLiteral(field, prop, P);
+        assignments.push({ kind: "literal", text: `${field}=${formatLiteral(value)}` });
+      }
+    }
+
+    const spec = `${tool.slug} ${assignments.map((a) => a.text).join(" ")}`.trim();
+    steps.push({ slug: tool.slug, spec, assignments });
+    usedSlugs.push(tool.slug);
+
+    console.log(chalk.gray(`\n  Running  ${spec}\n`));
+    const started = Date.now();
+    const result = await execute(tool.slug, literalInput(assignments));
+
+    if (!result.ok) {
+      console.log(chalk.red(`  ✗ ${result.error}`));
+      // Drop the step either way: only steps that actually ran belong in the
+      // replay command we hand back.
+      steps.pop();
+      usedSlugs.pop();
+      const again = await P.confirm({ message: "Change the inputs and retry?", default: true });
+      if (again) continue;
+      break;
+    }
+
+    console.log(chalk.green(`  ✓ completed in ${Date.now() - started}ms\n`));
+    console.log(chalk.bold("  Output"));
+    const fields = describeOutputFields(result.result);
+    renderObservedOutput(fields);
+    console.log();
+
+    outputs.push({ slug: tool.slug, value: result.result, fields });
+
+    if (fields.length === 0) break;
+    const more = await P.confirm({ message: "Send this output into another tool?", default: steps.length < 2 });
+    if (!more) break;
+  }
+
+  if (!steps.length) return { ok: false };
+
+  const pipeline = steps.map((s) => s.spec).join(" | ");
+  console.log(chalk.bold("\n  Pipeline\n"));
+  console.log(`    ${chalk.green(pipeline)}\n`);
+  console.log(chalk.dim(`  Replay it with:\n    nxb pipe '${pipeline}'\n`));
+
+  const save = await P.confirm({ message: "Save this pipeline?", default: false });
+  if (save) {
+    const name = await P.input({ message: "  Name", default: "my-pipeline" });
+    const { savePipeline } = await import("./pipelines.js");
+    const file = savePipeline(name, { pipeline, steps: steps.map((s) => ({ slug: s.slug, spec: s.spec })) });
+    console.log(chalk.green(`  Saved to ${file}`));
+    console.log(chalk.dim(`  Run it with:  nxb pipeline run ${name}\n`));
+  }
+
+  return { ok: true, spec: pipeline };
+}
+
+/** Build the input object for the trial run from literal assignments. */
+function literalInput(assignments) {
+  const input = {};
+  for (const a of assignments) {
+    const eq = a.text.indexOf("=");
+    if (eq === -1) continue;
+    const key = a.text.slice(0, eq);
+    const raw = a.text.slice(eq + 1);
+    if (raw.startsWith("$")) continue; // wired fields are not needed for a first run
+    try {
+      input[key] = JSON.parse(raw);
+    } catch {
+      input[key] = raw;
+    }
+  }
+  return input;
+}
+
+export { transformNames, parsePath };