@nexusbloom/cli 0.9.5 → 0.9.7

package/README.md

@@ -209,18 +209,20 @@ $ nxb pipe --build
     frequency-analyzer.total_words  integer  2
 ```
 
-When you wire a **collection** (an array or object) into a field, the builder
-offers the whole transform catalogue rather than only flagging a type clash —
-`len()` on an array, `join(",")`, `keys()`, `pick(field)` and the rest, listed
-with what each one does. You can chain them, and they are applied in the order
-you chose:
+Every wired field offers the whole transform catalogue, whatever its type, and
+nothing is applied on your behalf — a type clash is flagged on the choice list
+but no transform is chosen for you. So `chars()` on a string and `len()` on an
+array are both one step away, and you can chain as many as you like:
 
 ```bash
   frequency-analyzer → count  integer
-   Apply a transform to count? yes
-  Transform    › len
-                 len          length of a string, array or object
-   frequency-analyzer count=$character_frequency|len()
+  count: transform  (optional)
+    · none — use the value as it came
+    len          length of a string, array or object
+    chars        number of characters
+    join         array to a string, with a separator
+  Add another transform to count? yes
+    frequency-analyzer count=$character_frequency|len()|int()
 ```
 
 This produces the same `$path|transform()` syntax you can write by hand. Two
@@ -232,9 +234,40 @@ rather than emitting a spec that will not run:
   from a separator, so it refuses all of them.
 - **`|` cannot appear in an argument**, because it separates pipeline steps.
 
-A scalar type clash keeps its existing one-tap suggestion (`apply int()?`),
-since that is a fix rather than a choice. Run `nxb pipe --transforms` for the
-full catalogue with examples.
+Declining the list leaves the value as it came. If that produces a type error,
+`nxb doctor <slug>` and the plan-time check in `--dry-run` name the broken wire
+rather than the pipeline failing mid-run. Run `nxb pipe --transforms` for the
+same catalogue as a plain list.
+
+### Reusing an earlier step's output
+
+A bare `$path` always reads the **previous** step. When a pipeline needs two
+values carried forward, add `as=<name>` to the step that produces the one you
+want to keep, then address it by that name from anywhere later:
+
+```bash
+$ nxb pipe 'password-generator length=8 as=pw \
+    | lorem-generator count=$pw.password|chars()|str()   # use its length here \
+    | base64-tool text=$pw.password action=encode         # encode the password \
+    | base64-tool text=$result action=decode             # …and decode it again \
+    | echo-tool text=$pw.password'                       # …and use the original
+```
+
+Without a label that pipeline is impossible: the only way to reach the first
+step's password at the end is to run it a second time.
+
+- A label is read from the first path segment, so `$pw.password` and
+  `$pw` (the whole output) both work. Transforms chain as usual.
+- Labels are unique across a pipeline; a repeat is an error rather than a
+  silent last-one-wins.
+- `as=` only counts as a label in **last** position, so a tool with a real
+  input field named `as` is unaffected.
+- Plan-time type checking resolves labels too, so `--dry-run` still catches a
+  bad cast on a far connection instead of failing mid-run.
+
+The interactive builder offers this: after a step runs it asks whether to keep
+the output, and a kept output then appears in the field picker for every later
+step alongside the previous one.
 
 ### Saved pipelines
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusbloom/cli",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "NexusBloom CLI — run tools and workflows from your terminal",
   "type": "module",
   "bin": {

package/src/pipe.js

@@ -322,6 +322,24 @@ export function parsePipeline(spec) {
       throw new Error(`Invalid tool slug "${slug}"`);
     }
 
+    // A trailing `as=<label>` names this step's output so later steps can read
+    // it instead of only the immediately previous step. It is recognised only in
+    // last position, so a tool with a real field called `as` keeps working.
+    let label = null;
+    const last = tokens[tokens.length - 1];
+    if (last !== undefined && /^as=([a-zA-Z_][a-zA-Z0-9_]*)$/.test(last)) {
+      label = last.slice(3);
+      tokens.pop();
+    } else if (last !== undefined && /^as=/.test(last)) {
+      // Trailing `as=` that is not a valid identifier is far more likely a typo
+      // than a field the user meant to set, and silently becoming `as=<value>`
+      // would produce a confusing "no such field" much later.
+      throw new Error(
+        `Invalid label "${last.slice(3)}" — a label must start with a letter or _ and ` +
+          `contain only letters, digits and _ (e.g. as=pw).`
+      );
+    }
+
     const inputs = [];
     for (const token of tokens.slice(1)) {
       const eq = token.indexOf("=");
@@ -335,13 +353,55 @@ export function parsePipeline(spec) {
       const exprText = expr.kind === "literal" ? "" : `$${expr.headPath ?? ""}`;
       inputs.push({ field, expr, exprText });
     }
-    steps.push({ slug, inputs, raw: spec });
+    steps.push({ slug, inputs, raw: spec, label });
   }
 
   if (!steps.length) throw new Error("Empty pipeline.");
+
+  const seen = new Map();
+  for (const step of steps) {
+    if (!step.label) continue;
+    const first = seen.get(step.label);
+    if (first !== undefined) {
+      throw new Error(
+        `Duplicate label "${step.label}" on steps ${first + 1} and ${step.slug} — ` +
+          `labels name one step's output, so they must be unique.`
+      );
+    }
+    seen.set(step.label, steps.indexOf(step));
+  }
+
   return steps;
 }
 
+/**
+ * Resolve a connection's head path against the labelled outputs in scope.
+ *
+ * `$x` keeps its meaning — the previous step. `$name.field` reads `field` from
+ * whichever step was labelled `as=name`, at any distance, which is what lets a
+ * pipeline use an early value again much later.
+ *
+ * @returns {{label: string|null, upstream: any, accessors: Array}|null} null when
+ *   the head does not name a label, meaning the caller should use the old
+ *   previous-step behaviour.
+ */
+export function scopeToLabel(accessors, scope) {
+  if (!accessors.length || accessors[0].op !== "path") return null;
+  const segments = parsePath(accessors[0].path);
+  const head = segments[0];
+  if (typeof head !== "string" || !scope.has(head)) return null;
+
+  const rest = segments.slice(1);
+  return {
+    label: head,
+    upstream: scope.get(head),
+    accessors: [
+      { op: "path", path: rest.length ? formatPath(rest) : "$" },
+      ...accessors.slice(1),
+    ],
+  };
+}
+
 // ─── Plan ────────────────────────────────────────────────────────────────────
 
 /**
@@ -355,6 +415,8 @@ export async function buildPlan(steps, getManifest) {
   const planned = [];
   const issues = [];
   const produced = new Map(); // slug -> output field names it declares
+  const labelTypes = new Map(); // `as=name` -> that step's output schema
+  const labelSlug = new Map(); // `as=name` -> the slug that produced it
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
@@ -378,6 +440,10 @@ export async function buildPlan(steps, getManifest) {
     const outProps = info.manifest.output_schema?.properties || {};
     entry.outputs = Object.keys(outProps);
     produced.set(step.slug, outProps);
+    if (step.label) {
+      labelTypes.set(step.label, outProps);
+      labelSlug.set(step.label, step.slug);
+    }
 
     for (const input of step.inputs) {
       const prop = props[input.field];
@@ -399,37 +465,55 @@ export async function buildPlan(steps, getManifest) {
       }
 
       if (input.expr.kind === "connection") {
+        // Where does this connection read from? An `as=` label if the head names
+        // one, otherwise the immediately previous step as before.
+        const headSegments = parsePath(input.expr.headPath);
+        const head = headSegments[0];
+        const usesLabel = typeof head === "string" && labelTypes.has(head);
         const prev = i > 0 ? steps[i - 1] : null;
-        if (!prev) {
+        const sourceSlug = usesLabel ? labelSlug.get(head) : prev?.slug;
+        const sourceOut = usesLabel
+          ? labelTypes.get(head) || {}
+          : (produced.get(prev?.slug) || {});
+        // The segments after the label are the real path inside that output.
+        const restSegments = usesLabel ? headSegments.slice(1) : headSegments;
+
+        if (!usesLabel && !prev) {
           issues.push({ step: i, level: "error", message: `Nothing to read $${input.expr.headPath} from — it is the first step.` });
           field.verdict = "error";
         } else {
-          const prevOut = produced.get(prev.slug) || {};
-          const headSegments = parsePath(input.expr.headPath);
-          const leaf = headSegments[headSegments.length - 1];
-          const prevProp = headSegments.length === 1 ? prevOut[leaf] : undefined;
-          const prevDeclaresAny = Object.keys(prevOut).length > 0;
-          const known = headSegments.length === 0 || Boolean(prevProp) || !prevDeclaresAny;
+          const leaf = restSegments[restSegments.length - 1];
+          const sourceProp = restSegments.length === 1 ? sourceOut[leaf] : undefined;
+          const declaresAny = Object.keys(sourceOut).length > 0;
+          const known = restSegments.length === 0 || Boolean(sourceProp) || !declaresAny;
 
           field.source = {
-            slug: prev.slug,
-            path: input.expr.headPath,
-            pathLabel: formatPath(headSegments),
+            slug: sourceSlug,
+            label: usesLabel ? head : null,
+            path: usesLabel ? formatPath(restSegments) : input.expr.headPath,
+            pathLabel: formatPath(restSegments),
           };
-          field.sourceTypes = schemaTypes(prevProp);
+          field.sourceTypes = schemaTypes(sourceProp);
           field.sourceKnown = known;
-
-          // Walk the accessors to work out the type that actually arrives.
-          field.resultTypes = simulateTypes(input.expr.accessors, field.sourceTypes);
+          const srcName = usesLabel
+            ? `${head}.${formatPath(restSegments) || "(root)"}`
+            : `${sourceSlug}.${input.expr.headPath || "(root)"}`;
+
+          // Walk the accessors to work out the type that actually arrives. The
+          // label segment is not part of the data path, so it is dropped first.
+          const simAccessors = usesLabel
+            ? [{ op: "path", path: formatPath(restSegments) }, ...input.expr.accessors.slice(1)]
+            : input.expr.accessors;
+          field.resultTypes = simulateTypes(simAccessors, field.sourceTypes);
           // A path used *after* a transform cannot be typed from the schema.
-          if (!known || headSegments.length > 1) field.staticallyUnknown = true;
+          if (!known || restSegments.length > 1) field.staticallyUnknown = true;
 
           if (!known) {
             field.verdict = "unknown-source";
             issues.push({
               step: i,
               level: "warn",
-              message: `"${prev.slug}" does not declare output "${input.expr.headPath}" — checked at runtime.`,
+              message: `"${sourceSlug}" does not declare output "${formatPath(restSegments)}" — checked at runtime.`,
             });
           } else if (field.targetTypes.length && field.resultTypes.length) {
             const compat = compatibility(field.resultTypes[0], field.targetTypes);
@@ -439,18 +523,18 @@ export async function buildPlan(steps, getManifest) {
               issues.push({
                 step: i,
                 level: "error",
-                message: `${prev.slug}.${input.expr.headPath || "(root)"} is ${typeLabel(field.resultTypes)} but ${step.slug}.${input.field} wants ${typeLabel(field.targetTypes)} — add |${compat.suggestion}`,
+                message: `${srcName} is ${typeLabel(field.resultTypes)} but ${step.slug}.${input.field} wants ${typeLabel(field.targetTypes)} — add |${compat.suggestion}`,
               });
             } else if (compat.level === "lossy") {
               field.verdict = "lossy";
               issues.push({
                 step: i,
                 level: "warn",
-                message: `${prev.slug}.${input.expr.headPath || "(root)"} → ${step.slug}.${input.field} may lose precision (${compat.note}).`,
+                message: `${srcName} → ${step.slug}.${input.field} may lose precision (${compat.note}).`,
               });
             } else if (compat.level === "invalid") {
               field.verdict = "error";
-              issues.push({ step: i, level: "error", message: `${prev.slug}.${input.expr.headPath || "(root)"} → ${step.slug}.${input.field}: ${compat.note}.` });
+              issues.push({ step: i, level: "error", message: `${srcName} → ${step.slug}.${input.field}: ${compat.note}.` });
             } else {
               field.verdict = "ok";
             }
@@ -538,6 +622,8 @@ export async function runPipeline({
 }) {
   const outputs = new Array(steps.length).fill(undefined);
   const logs = [];
+  // Labelled step outputs, readable from any later step.
+  const scope = new Map();
 
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
@@ -563,13 +649,24 @@ export async function runPipeline({
         continue;
       }
 
-      const upstream = outputs[i - 1];
+      // An explicit `as=` label wins over the implicit previous step.
+      const labelled = scopeToLabel(expr.accessors, scope);
+      const upstream = labelled ? labelled.upstream : outputs[i - 1];
       if (upstream === undefined) {
-        throw new PipeError(`Step ${i + 1}: ${step.slug} reads $${expr.headPath} but step ${i} has not run.`);
+        throw new PipeError(
+          labelled
+            ? `Step ${i + 1}: ${step.slug} reads $${expr.headPath}, but no step produced "${labelled.label}".`
+            : i === 0
+              ? `Step 1: ${step.slug} reads $${expr.headPath}, but there is no earlier step. ` +
+                `A connection reads the previous step, or a step you labelled with as=<name>.`
+              : `Step ${i + 1}: ${step.slug} reads $${expr.headPath} but step ${i} has not run.`
+        );
       }
 
-      let value = resolveAccessors(upstream, expr.accessors);
-      const fromLabel = `${field.source?.slug ?? `step ${i}`}.${expr.headPath || "(root)"}`;
+      let value = resolveAccessors(upstream, labelled ? labelled.accessors : expr.accessors);
+      const fromLabel = labelled
+        ? `${labelled.label}.${formatPath(parsePath(expr.headPath).slice(1)) || "(root)"}`
+        : `${field.source?.slug ?? `step ${i}`}.${expr.headPath || "(root)"}`;
 
       // A connection that resolves to nothing is always an error: silently
       // sending `undefined` hides the broken wire behind whatever the tool
@@ -618,6 +715,7 @@ export async function runPipeline({
 
     const value = result?.ok === true ? result.result : result;
     outputs[i] = value;
+    if (step.label) scope.set(step.label, value);
     onStep({ phase: "done", index: i, step, input, output: value, durationMs: result?.durationMs });
   }
 
@@ -645,7 +743,11 @@ export function renderPlan(plan) {
       lines.push(chalk.red(`  ✗ ${step.slug} — not found`));
       continue;
     }
-    lines.push(chalk.bold(`  ${step.slug}`));
+    lines.push(
+      step.label
+        ? chalk.bold(`  ${step.slug}`) + chalk.magenta(`  as=${step.label}`)
+        : chalk.bold(`  ${step.slug}`)
+    );
 
     for (const f of step.fields) {
       const target = chalk.cyan(f.field);
@@ -656,11 +758,22 @@ export function renderPlan(plan) {
       } else if (f.expr.kind === "stdin") {
         lines.push(`    ${target} = ${chalk.magenta("@in")} ${chalk.gray(`(${targetType || "any"})`)}`);
       } else {
-        const chain = (f.expr.accessors || [])
+        const accessors = f.expr.accessors || [];
+        // A labelled source puts the label *and* the rest of the path in the head
+        // accessor, so it is displayed the way it was written rather than with the
+        // producing slug glued in front.
+        const labelled = Boolean(f.source?.label);
+        const rest = accessors.slice(labelled ? 1 : 0);
+        const chain = rest
           .map((a) => (a.op === "transform" ? `|${a.name}` : a.path))
           .join("");
+        const head = labelled
+          ? `${f.source.label}${f.source.path === "$" ? "" : `.${f.source.path}`}`
+          : `${f.source?.slug ?? "?"}`;
         const arrow = chalk.gray("←");
-        const src = chalk.dim(`${f.source?.slug ?? "?"}${chain.startsWith(".") || chain.startsWith("|") ? chain : `.${chain}`}`);
+        const src = chalk.dim(
+          `${head}${labelled ? chain : chain.startsWith(".") || chain.startsWith("|") ? chain : `.${chain}`}`
+        );
         const got = f.resultTypes?.length ? typeLabel(f.resultTypes) : "runtime";
         const mark =
           f.verdict === "needs-cast" || f.verdict === "error" ? chalk.red("✗")

package/src/values.js

@@ -13,6 +13,8 @@
  */
 
 /** Distinguishes "the field is absent" from "the field holds undefined". */
+import { createHash, randomUUID } from "crypto";
+
 export const MISSING = Symbol("missing");
 
 /**
@@ -96,6 +98,40 @@ export function formatPath(segments) {
   return out;
 }
 
+// ─── Helpers for the computed transforms ─────────────────────────────────────
+
+/**
+ * Compare loosely enough that `eq(200)` matches a JSON number but `eq("200")`
+ * also matches the string a tool happened to return, while still refusing to
+ * claim `[1]` equals `[1]`.
+ */
+function coerceLike(other, sample) {
+  if (typeof other === "string" && typeof sample === "number") {
+    const n = Number(other);
+    return isNaN(n) ? other : n;
+  }
+  return other;
+}
+
+/**
+ * Equality that forgives a number arriving as text, without extending that
+ * forgiveness to containers. Comparing by string would make two separate
+ * `[1]`s equal and two `{a:1}`s equal, which is never what "are these the same"
+ * should answer.
+ */
+function looseEqual(a, b) {
+  if (a === b) return true;
+  const bothPrimitives =
+    (a === null || typeof a !== "object") && (b === null || typeof b !== "object");
+  if (!bothPrimitives) return false;
+  return String(a) === String(b);
+}
+
+/** Stable hash of a stringified value, for change detection and cache keys. */
+function digest(value, algorithm) {
+  return createHash(algorithm).update(toStr(value), "utf8").digest("hex");
+}
+
 // ─── Coercion helpers ────────────────────────────────────────────────────────
 
 const toStr = (v) => {
@@ -204,6 +240,212 @@ export const TRANSFORMS = {
     return r;
   },
   default: (v, fallback) => (v === MISSING || v === undefined || v === null || v === "" ? fallback : v),
+
+  // — arithmetic —
+  //
+  // The tools in a catalogue rarely line up numerically: one returns a count, the
+  // next wants a word count. These fill the gap without a dedicated tool, which is
+  // the difference between "add a tool" and "compose what exists".
+  //
+  // A wrong input type returns the value untouched rather than throwing or
+  // coercing, so a transform never silently invents a number.
+  add: (v, n) => (typeof v === "number" && isFinite(v) ? v + Number(n) : v),
+  sub: (v, n) => (typeof v === "number" && isFinite(v) ? v - Number(n) : v),
+  mul: (v, n) => (typeof v === "number" && isFinite(v) ? v * Number(n) : v),
+  div: (v, n) => (typeof v === "number" && isFinite(v) && Number(n) !== 0 ? v / Number(n) : v),
+  mod: (v, n) => (typeof v === "number" && isFinite(v) && Number(n) !== 0 ? v % Number(n) : v),
+  inc: (v) => (typeof v === "number" && isFinite(v) ? v + 1 : v),
+  dec: (v) => (typeof v === "number" && isFinite(v) ? v - 1 : v),
+  neg: (v) => (typeof v === "number" && isFinite(v) ? -v : v),
+  abs: (v) => (typeof v === "number" && isFinite(v) ? Math.abs(v) : v),
+  pow: (v, n) => (typeof v === "number" && isFinite(v) ? v ** Number(n) : v),
+  round: (v, p = 0) => (typeof v === "number" && isFinite(v) ? Number(v.toFixed(Number(p))) : v),
+  floor: (v) => (typeof v === "number" && isFinite(v) ? Math.floor(v) : v),
+  ceil: (v) => (typeof v === "number" && isFinite(v) ? Math.ceil(v) : v),
+  clamp: (v, lo, hi) =>
+    typeof v === "number" && isFinite(v)
+      ? Math.min(Math.max(v, Number(lo)), Number(hi))
+      : v,
+
+  // Aggregate — the whole input array collapses to one number.
+  sum: (v) => (Array.isArray(v) ? v.filter((n) => typeof n === "number").reduce((a, b) => a + b, 0) : v),
+  avg: (v) => {
+    if (!Array.isArray(v)) return v;
+    const nums = v.filter((n) => typeof n === "number");
+    return nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : MISSING;
+  },
+  min: (v) => (Array.isArray(v) && v.length ? Math.min(...v.filter((n) => typeof n === "number")) : v),
+  max: (v) => (Array.isArray(v) && v.length ? Math.max(...v.filter((n) => typeof n === "number")) : v),
+  // Sum one field across an array of objects — the common "total of the column".
+  sumBy: (v, key) => {
+    if (!Array.isArray(v)) return v;
+    return v
+      .map((r) => getPath(r, key))
+      .filter((n) => typeof n === "number")
+      .reduce((a, b) => a + b, 0);
+  },
+
+  // — comparison —
+  //
+  // These return real booleans, so they are the input to `then()` and to any tool
+  // taking a boolean. A non-matching value is `false`, never MISSING.
+  eq: (v, other) => looseEqual(v, other),
+  ne: (v, other) => !looseEqual(v, other),
+  gt: (v, n) => typeof v === "number" && isFinite(v) && v > Number(n),
+  gte: (v, n) => typeof v === "number" && isFinite(v) && v >= Number(n),
+  lt: (v, n) => typeof v === "number" && isFinite(v) && v < Number(n),
+  lte: (v, n) => typeof v === "number" && isFinite(v) && v <= Number(n),
+  between: (v, lo, hi) => typeof v === "number" && isFinite(v) && v >= Number(lo) && v <= Number(hi),
+  includes: (v, needle) =>
+    typeof v === "string"
+      ? v.includes(needle)
+      : Array.isArray(v)
+        ? v.some((x) => x === needle)
+        : false,
+  startsWith: (v, s) => typeof v === "string" && v.startsWith(s),
+  endsWith: (v, s) => typeof v === "string" && v.endsWith(s),
+  // Regex source only — a pattern with spaces or flags cannot be expressed, and a
+  // bad pattern is the user's typo rather than something to guess at.
+  matches: (v, re) => {
+    if (typeof v !== "string" || !re) return false;
+    try {
+      return new RegExp(String(re)).test(v);
+    } catch {
+      return false;
+    }
+  },
+  isEmpty: (v) =>
+    v === MISSING || v === undefined || v === null || v === "" ||
+    (Array.isArray(v) && v.length === 0) ||
+    (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0),
+
+  // — branching —
+  //
+  // `then(cond, whenTrue, whenFalse)` is what a linear pipeline was missing: pick
+  // between two values on a condition, without a step to do it. `coalesce` is the
+  // safe default chain that does not need a condition at all.
+  then: (v, cond, whenTrue, whenFalse) => {
+    const test = typeof cond === "boolean" ? cond : v === true;
+    return test ? whenTrue : whenFalse === undefined ? MISSING : whenFalse;
+  },
+  coalesce: (v, ...fallbacks) => {
+    if (v !== MISSING && v !== undefined && v !== null && v !== "") return v;
+    for (const f of fallbacks) {
+      if (f !== MISSING && f !== undefined && f !== null && f !== "") return f;
+    }
+    return MISSING;
+  },
+
+  // — arrays —
+  //
+  // `pluck` is the one that unlocks the most: it turns an array of records into a
+  // flat array of one field, which everything above (`len`, `sort`, `sumBy`,
+  // `join`) can then work on.
+  pluck: (v, key) =>
+    Array.isArray(v) ? v.map((row) => getPath(row, key)) : v,
+  unique: (v) => (Array.isArray(v) ? [...new Set(v)] : v),
+  compact: (v) =>
+    Array.isArray(v) ? v.filter((x) => x !== undefined && x !== null && x !== "") : v,
+  flatten: (v) => (Array.isArray(v) ? v.flat(Infinity) : v),
+  chunk: (v, n) => {
+    if (!Array.isArray(v)) return v;
+    const size = Math.max(1, Number(n) || 1);
+    const out = [];
+    for (let i = 0; i < v.length; i += size) out.push(v.slice(i, i + size));
+    return out;
+  },
+  without: (v, needle) => (Array.isArray(v) ? v.filter((x) => x !== needle) : v),
+  // Keep array elements whose field passes a comparison: where("status","eq",200).
+  where: (v, key, op, operand) => {
+    if (!Array.isArray(v)) return v;
+    const test = (row) => {
+      const got = getPath(row, key);
+      switch (op) {
+        case "eq": return looseEqual(got, operand);
+        case "ne": return !looseEqual(got, operand);
+        case "gt": return typeof got === "number" && got > Number(operand);
+        case "gte": return typeof got === "number" && got >= Number(operand);
+        case "lt": return typeof got === "number" && got < Number(operand);
+        case "lte": return typeof got === "number" && got <= Number(operand);
+        case "contains": return String(got ?? "").includes(String(operand));
+        case "exists": return got !== MISSING && got !== undefined && got !== null;
+        default: return false;
+      }
+    };
+    return v.filter(test);
+  },
+
+  // — naming and shape —
+  title: (v) => toStr(v).replace(/\b\w/g, (c) => c.toUpperCase()),
+  camel: (v) => toStr(v).replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : "")).replace(/^(.)/, (c) => c.toLowerCase()),
+  snake: (v) => toStr(v).replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase(),
+  kebab: (v) => toStr(v).replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase(),
+  slugify: (v) =>
+    toStr(v)
+      .toLowerCase()
+      .normalize("NFKD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, ""),
+  truncate: (v, n, ellipsis = "…") => {
+    const s = toStr(v);
+    const max = Math.max(0, Number(n) || 0);
+    if (s.length <= max) return s;
+    // Prefer a word boundary, but only if one is close enough that truncating to
+    // it does not throw away most of what was asked for.
+    const hard = s.slice(0, max);
+    const space = hard.lastIndexOf(" ");
+    const cut = space > max * 0.6 ? hard.slice(0, space).replace(/\s+$/, "") : hard;
+    return cut + ellipsis;
+  },
+  repeat: (v, n) => toStr(v).repeat(Math.max(0, Number(n) || 0)),
+  // Show the first and last few characters, e.g. mask(4) → "jTI…Nj".
+  mask: (v, n = 3) => {
+    const s = toStr(v);
+    const keep = Math.max(0, Number(n) || 0);
+    if (s.length <= keep * 2) return s;
+    return `${s.slice(0, keep)}${"…".repeat(1)}${s.slice(-keep)}`;
+  },
+
+  // — encoding and identity —
+  //
+  // Hashing here is for change detection and cache keys, never for passwords.
+  md5: (v) => digest(v, "md5"),
+  sha1: (v) => digest(v, "sha1"),
+  sha256: (v) => digest(v, "sha256"),
+  base64: (v) => Buffer.from(toStr(v), "utf8").toString("base64"),
+  unbase64: (v) => {
+    const text = toStr(v).trim();
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(text)) return MISSING;
+    try {
+      const bytes = Buffer.from(text, "base64");
+      // Buffer.from silently drops anything outside the alphabet, so the only
+      // way to notice the input was never base64 is to re-encode and compare.
+      // Garbage bytes are worse than an honest MISSING.
+      const reencoded = bytes.toString("base64").replace(/=+$/, "");
+      if (reencoded !== text.replace(/=+$/, "")) return MISSING;
+      return bytes.toString("utf8");
+    } catch {
+      return MISSING;
+    }
+  },
+  urlEncode: (v) => encodeURIComponent(toStr(v)),
+  urlDecode: (v) => {
+    try {
+      return decodeURIComponent(toStr(v));
+    } catch {
+      return MISSING;
+    }
+  },
+  uuid: () => randomUUID(),
+
+  // — introspection —
+  type: (v) => (v === MISSING ? "missing" : Array.isArray(v) ? "array" : v === null ? "null" : typeof v),
+  isArray: (v) => Array.isArray(v),
+  isString: (v) => typeof v === "string",
+  isNumber: (v) => typeof v === "number" && isFinite(v),
+  isObject: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+  isBool: (v) => typeof v === "boolean",
 };
 
 /** Transforms that are no-ops on their argument order, used for plan hints. */
@@ -217,6 +459,20 @@ export const TRANSFORM_ARITY = {
   sort: 2,
   pick: 2,
   default: 2,
+
+  add: 2, sub: 2, mul: 2, div: 2, mod: 2, pow: 2,
+  round: 2, clamp: 3, sumBy: 2,
+  eq: 2, ne: 2, gt: 2, gte: 2, lt: 2, lte: 2,
+  between: 3, includes: 2, startsWith: 2, endsWith: 2, matches: 2,
+  then: 4,
+  // Arity is how many arguments the *builder* asks for, which is one less than
+  // the argument count of the hand-written form for a variadic transform.
+  // coalesce takes any number of fallbacks; prompting for a fixed count would
+  // understate it, so the builder asks for one and a written pipeline may list
+  // as many as it likes.
+  coalesce: 2,
+  pluck: 2, chunk: 2, without: 2, where: 4,
+  truncate: 3, repeat: 2, mask: 2,
 };
 
 export function transformNames() {
@@ -260,6 +516,71 @@ export const TRANSFORM_DOCS = {
   unjson: "parse a JSON string",
   pick: "one field out of an object",
   default: "value to use when the path is missing",
+  // The catalogue is grouped by purpose; `nxb pipe --transforms` and the
+  // builder's picker both read from here, so a transform and its description
+  // are always edited together.
+  add: "add a number",
+  sub: "subtract a number",
+  mul: "multiply by a number",
+  div: "divide by a number",
+  mod: "remainder after division",
+  pow: "raise to a power",
+  inc: "add one",
+  dec: "subtract one",
+  neg: "negate",
+  abs: "absolute value",
+  round: "round to N decimal places",
+  floor: "round down to an integer",
+  ceil: "round up to an integer",
+  clamp: "keep a number between a low and a high",
+  sum: "add up every number in an array",
+  avg: "average of every number in an array",
+  min: "smallest number in an array",
+  max: "largest number in an array",
+  sumBy: "add up one field across an array of objects",
+  eq: "is it equal to a value",
+  ne: "is it different from a value",
+  gt: "is it greater than a number",
+  gte: "is it at least a number",
+  lt: "is it less than a number",
+  lte: "is it at most a number",
+  between: "is a number within a low and a high",
+  includes: "does a string or array contain a value",
+  startsWith: "does a string start with text",
+  endsWith: "does a string end with text",
+  matches: "does a string match a regular expression",
+  isEmpty: "is the value empty — blank, [], or {}",
+  then: "choose between two values on a condition",
+  coalesce: "first value that is not empty",
+  pluck: "pull one field out of every object in an array",
+  unique: "remove duplicates from an array",
+  compact: "drop empty values from an array",
+  flatten: "flatten a nested array",
+  chunk: "split an array into fixed-size groups",
+  without: "remove every occurrence of a value",
+  where: "keep array items whose field passes a test",
+  title: "Title Case",
+  camel: "camelCase",
+  snake: "snake_case",
+  kebab: "kebab-case",
+  slugify: "url-safe slug",
+  truncate: "shorten to N characters",
+  repeat: "repeat a string N times",
+  mask: "hide the middle, e.g. jTI…Nj",
+  md5: "MD5 hex digest",
+  sha1: "SHA-1 hex digest",
+  sha256: "SHA-256 hex digest",
+  base64: "Base64-encode text",
+  unbase64: "decode Base64 text",
+  urlEncode: "percent-encode for a URL",
+  urlDecode: "decode percent-encoding",
+  uuid: "a random UUID",
+  type: "the value's type as text",
+  isArray: "is it an array",
+  isString: "is it text",
+  isNumber: "is it a number",
+  isObject: "is it an object",
+  isBool: "is it true or false",
 };
 
 /**
@@ -284,8 +605,32 @@ export const TRANSFORM_GROUPS = [
     names: ["int", "float", "num", "str", "bool"] },
   { label: "json / unjson", doc: "serialise / parse",
     names: ["json", "unjson"] },
-  { label: "default(v)", doc: "supply a value when the path is missing",
-    names: ["default"] },
+  { label: "default(v) / coalesce(a,b,…) / then(cond,a,b)", doc: "supply a value when one is missing, or choose on a condition",
+    names: ["default", "coalesce", "then"] },
+  { label: "eq / ne / gt / gte / lt / lte / between(a,b)", doc: "compare — the result is true or false",
+    names: ["eq", "ne", "gt", "gte", "lt", "lte", "between"] },
+  { label: "includes / startsWith / endsWith / matches(re) / isEmpty", doc: "test text and arrays",
+    names: ["includes", "startsWith", "endsWith", "matches", "isEmpty"] },
+  { label: "pluck(field) / where(field,op,value)", doc: "select out of an array of records",
+    names: ["pluck", "where"] },
+  { label: "unique / compact / flatten / chunk(n) / without(v)", doc: "reshape an array",
+    names: ["unique", "compact", "flatten", "chunk", "without"] },
+  { label: "add(n) / sub(n) / mul(n) / div(n) / mod(n) / pow(n)", doc: "arithmetic on a number",
+    names: ["add", "sub", "mul", "div", "mod", "pow"] },
+  { label: "inc / dec / neg / abs / round(p) / floor / ceil / clamp(lo,hi)", doc: "adjust a number",
+    names: ["inc", "dec", "neg", "abs", "round", "floor", "ceil", "clamp"] },
+  { label: "sum / avg / min / max / sumBy(field)", doc: "collapse an array to one number",
+    names: ["sum", "avg", "min", "max", "sumBy"] },
+  { label: "title / camel / snake / kebab / slugify", doc: "change a string's shape",
+    names: ["title", "camel", "snake", "kebab", "slugify"] },
+  { label: "truncate(n) / repeat(n) / mask(n)", doc: "shorten, repeat or hide part of a string",
+    names: ["truncate", "repeat", "mask"] },
+  { label: "md5 / sha1 / sha256 / base64 / unbase64", doc: "digest or encode — for fingerprints, not secrets",
+    names: ["md5", "sha1", "sha256", "base64", "unbase64"] },
+  { label: "urlEncode / urlDecode / uuid", doc: "URL and identity helpers",
+    names: ["urlEncode", "urlDecode", "uuid"] },
+  { label: "type / isArray / isString / isNumber / isObject / isBool", doc: "what is this value",
+    names: ["type", "isArray", "isString", "isNumber", "isObject", "isBool"] },
 ];
 
 /**
@@ -350,14 +695,18 @@ export function validateTransformArg(raw) {
  * @param {Array<{name: string, args: any[]}>} chain
  * @returns {any|typeof MISSING}
  */
+/** Transforms permitted to replace a missing value with a fallback. */
+const FALLBACK_TRANSFORMS = new Set(["default", "coalesce"]);
+
 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 missing value stays missing unless the transform is explicitly allowed to
+    // supply a fallback — `default(v)` and `coalesce(…)`. Anything else would
+    // be inventing a value the tool never produced.
+    if (cur === MISSING && !FALLBACK_TRANSFORMS.has(step.name)) 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 || []));

package/src/wizard.js

@@ -42,10 +42,9 @@ import {
   formatTransformCall,
   validateTransformArg,
   TRANSFORM_DOCS,
-  TRANSFORMS,
   MISSING,
 } from "./values.js";
-import { parseValueExpr, resolveAccessors } from "./pipe.js";
+import { parseValueExpr, resolveAccessors, scopeToLabel } from "./pipe.js";
 import { isInteractive } from "./ui.js";
 import { renderHeader } from "./ui.js";
 
@@ -165,7 +164,7 @@ async function promptLiteral(field, prop, P = defaultPrompts) {
  * 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) {
+async function wireFields(manifest, sources, P = defaultPrompts) {
   const props = manifest.input_schema?.properties || {};
   const required = new Set(manifest.input_schema?.required || []);
   const assignments = [];
@@ -179,25 +178,30 @@ async function wireFields(manifest, prevSlug, prevFields, P = defaultPrompts) {
         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 },
-        };
-      }),
+      ...sources.flatMap((src) =>
+        src.fields.map((f) => {
+          const path = formatPath(f.path);
+          // A kept output is addressed by its label, the previous step by path.
+          const wire = src.label ? `${src.label}.${path}` : 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")
+            : "";
+          const tag = src.label ? chalk.magenta(` ${src.label}·`) : "";
+          return {
+            name: `${chalk.cyan(wire.padEnd(24))} ${chalk.gray(from.padEnd(8))} ${chalk.dim(preview(f.value, 24))}${tag}${flag}`,
+            value: { kind: "wire", path: wire, label: src.label || null },
+          };
+        })
+      ),
       ...(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(" *") : ""}`,
+      message: `${sources[0]?.label || sources[0]?.slug || "?"} → ${chalk.cyan(field)}  ${chalk.gray(typeLabel(targetTypes))}${required.has(field) ? chalk.red(" *") : ""}`,
       choices,
       pageSize: 14,
     });
@@ -210,18 +214,18 @@ async function wireFields(manifest, prevSlug, prevFields, P = defaultPrompts) {
       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" };
-    // Offer transforms where one can do something: a type clash makes one
-    // necessary, and a collection is what `len`/`first`/`join`/`keys` exist for.
-    // Asking after every wire would be a pointless extra question on the common
-    // scalar-to-scalar case, where no transform applies anyway.
-    const worthTransforming = compat.level === "cast" || from === "array" || from === "object";
-    const chain = worthTransforming
-      ? await promptTransformChain({ field, targetTypes, compat, from, P })
-      : "";
+    const chosen = sources
+      .flatMap((src) => src.fields.map((f) => ({ src, f })))
+      .find(({ src, f }) => {
+        const path = formatPath(f.path);
+        return src.label ? `${src.label}.${path}` === choice.path : path === choice.path;
+      });
+    const from = chosen ? inferType(chosen.f.value) : "unknown";
+    // Any wired value can be reshaped, whatever its type — `len()` on a string
+    // is as legitimate as on an array, and the wizard has no business deciding
+    // which transforms are worth offering. The type flag on the choice above is
+    // the only nudge: it marks a clash without applying anything.
+    const chain = await promptTransformChain(field, P);
 
     assignments.push({ kind: "wire", text: `${field}=$${choice.path}${chain}` });
   }
@@ -232,69 +236,71 @@ async function wireFields(manifest, prevSlug, prevFields, P = defaultPrompts) {
 /**
  * Ask which transforms to apply to a wired value.
  *
- * Two things are happening here, in order. First a *required* cast — if the
- * source type cannot widen into the field's type, the suggestion is offered
- * directly, because without it the pipeline cannot run. Then the whole
- * catalogue: any field can be reshaped, not just the ones with a type clash,
- * since "how many items came back" is a question `len()` answers and no type
- * mismatch hints at.
+ * One question, always, with the whole catalogue in it — no type-based
+ * narrowing and no suggestion picked on the user's behalf. "How long is this
+ * string" is answered by `chars()` and no type mismatch hints at it, so gating
+ * the list on whether a cast happens to be needed would hide transforms people
+ * reach for. Declining is the first choice, so the common case costs one
+ * keystroke.
  *
- * The returned string is appended to `$path`, so it already carries its own
- * leading `|`.
+ * The returned string is appended to `$path`, so it carries its own `|`.
  */
-async function promptTransformChain({ field, targetTypes, compat, from, P }) {
-  // A collection feeding a scalar field is reported as a cast, but `first()` is
-  // a poor guess there — the usual intent is to measure or reshape it (`len`,
-  // `join`, `pick`). So collections go straight to the catalogue, which offers
-  // `first` anyway. A genuine scalar clash keeps its original single question:
-  // one tap to fix a type error beats making everyone walk a picker for it.
-  if (from === "array" || from === "object") {
-    let chain = "";
-    for (;;) {
-      const more = await P.confirm({
-        message: chain ? `Add another transform to ${field}?` : `Apply a transform to ${field}?`,
-        default: false,
-      });
-      if (!more) break;
-      const built = await promptOneTransform(P);
-      if (!built) break;
-      chain += built;
-    }
-    return chain;
-  }
+async function promptTransformChain(field, P) {
+  const picked = await P.search({
+    message: `${field}: transform${chalk.gray("  (optional)")}`,
+    source: (term) => transformChoices(term, { withNone: true }),
+    pageSize: 15,
+  });
+
+  // `null` is the "use it as it came" row.
+  if (!picked) return "";
 
-  if (compat.level === "cast" && compat.suggestion) {
-    const use = await P.confirm({
-      message: `${field} expects ${typeLabel(targetTypes)} — apply ${chalk.cyan(compat.suggestion)}?`,
-      default: true,
+  let chain = await buildTransform(picked, P);
+  for (;;) {
+    const more = await P.confirm({
+      message: `Add another transform to ${field}?`,
+      default: false,
+    });
+    if (!more) break;
+    const next = await P.search({
+      message: `${field}: another transform`,
+      source: (term) => transformChoices(term, { withNone: true }),
+      pageSize: 15,
     });
-    if (use) return await buildSuggestedTransform(compat.suggestion, P);
+    if (!next) break;
+    chain += await buildTransform(next, P);
   }
-
-  return "";
+  return chain;
 }
 
 /**
- * Turn a `compatibility()` suggestion into a real transform call.
- *
- * Suggestions arrive as `int()`, `first()` — but also `pick(field)`, which
- * names an argument it cannot fill in. Anything inside the parens is a
- * placeholder rather than a value, so it prompts. `default()` is the awkward
- * case: the suggestion shows no argument even though the transform needs one,
- * so the arity is topped up from `TRANSFORM_ARITY` instead of emitting
- * `|default()`, which `parseTransform` rejects.
+ * Rows for the searchable transform picker. `withNone` keeps "use as-is" pinned
+ * to the top so it survives a search term that matches no transform.
  */
-async function buildSuggestedTransform(suggestion, P) {
-  const m = String(suggestion).match(/^([a-z_][a-z0-9_]*)(?:\((.*)\))?$/i);
-  if (!m) return "";
-  const name = m[1];
-  if (!Object.hasOwn(TRANSFORMS, name)) return "";
-  const needsArg = Boolean((m[2] || "").trim()) || transformArgCount(name) > 0;
-
-  if (!needsArg) return formatTransformCall(name);
+function transformChoices(term, { withNone = false } = {}) {
+  const skip = withNone
+    ? [{ value: null, name: chalk.gray("· none — use the value as it came") }]
+    : [];
+  const hits = term ? rankTransforms(term) : transformNames();
+  return [
+    ...skip,
+    // No cap: this is a searchable list, so it paginates and scrolls. Truncating
+    // here silently hid every transform past the cut-off, which is unreachable
+    // by typing the name you can see.
+    ...hits.map((n) => ({
+      value: n,
+      name: `${chalk.cyan(n.padEnd(10))} ${chalk.dim(TRANSFORM_DOCS[n] || "")}`,
+    })),
+  ];
+}
 
+/**
+ * Build one transform call, prompting for whatever arguments it needs.
+ * @returns {Promise<string>} e.g. `|len()` or `|get(0)`
+ */
+async function buildTransform(name, P) {
   const args = [];
-  for (let i = 0; i < Math.max(1, transformArgCount(name)); i++) {
+  for (let i = 0; i < transformArgCount(name); i++) {
     args.push(
       await P.input({
         message: `${name}()  argument ${i + 1}`,
@@ -305,34 +311,16 @@ async function buildSuggestedTransform(suggestion, P) {
   return formatTransformCall(name, args);
 }
 
-/**
- * Pick one transform from the catalogue and ask for whatever it needs.
- * @returns {Promise<string>} e.g. `|len()` or `|get(0)`
- */
-async function promptOneTransform(P) {
-  const names = transformNames();
-  const name = await P.select({
-    message: "Transform",
-    source: async (term) => {
-      const hits = rankTransforms(term);
-      return (term ? hits : names).slice(0, 50).map((n) => ({
-        value: n,
-        name: `${chalk.cyan(n.padEnd(10))} ${chalk.dim(TRANSFORM_DOCS[n] || "")}`,
-      }));
-    },
-    pageSize: 15,
-  });
-
-  let args = [];
-  for (let i = 0; i < transformArgCount(name); i++) {
-    const answer = await P.input({
-      message: `${name}()  argument ${i + 1}`,
-      validate: (v) => validateTransformArg(v),
-    });
-    args.push(answer);
+/** Suggest a label for a step: short, derived from the slug, not already taken. */
+function defaultLabel(slug, taken) {
+  const base = String(slug).replace(/[^a-zA-Z0-9_]/g, "").slice(0, 4) || "out";
+  const safe = /^[a-zA-Z_]/.test(base) ? base : `_${base}`;
+  if (!taken.has(safe)) return safe;
+  for (let n = 2; n < 100; n++) {
+    const next = `${safe}${n}`;
+    if (!taken.has(next)) return next;
   }
-
-  return formatTransformCall(name, args);
+  return safe;
 }
 
 /** Rank transforms by name and description, so "array" finds `join`. */
@@ -349,6 +337,10 @@ function formatLiteral(value) {
     return JSON.stringify(value);
   }
   if (typeof value === "string" && value === "") return '""';
+  // An object or array would otherwise land in the spec as "[object Object]",
+  // which is valid-looking and parses as neither JSON nor the intended value.
+  if (value !== null && typeof value === "object") return JSON.stringify(value);
+  if (value === null || value === undefined) return "null";
   return String(value);
 }
 
@@ -379,6 +371,11 @@ export async function buildWizard(opts = {}) {
 
   const steps = [];
   const outputs = [];
+  // Outputs the user chose to keep, readable from any later step. `scope` holds
+  // the raw output so it can be handed straight to `scopeToLabel`; `kept` keeps
+  // the metadata the picker needs to describe it.
+  const scope = new Map();
+  const kept = [];
 
   for (;;) {
     renderHeader(
@@ -396,11 +393,16 @@ export async function buildWizard(opts = {}) {
       continue;
     }
 
-    // Wire from the previous step, if there is one.
+    // Wire from the previous step and from anything kept earlier.
     let assignments = [];
-    if (outputs.length) {
-      const prev = outputs[outputs.length - 1];
-      assignments = await wireFields(manifest, prev.slug, prev.fields, P);
+    const sources = [
+      ...outputs.slice().reverse().map((o) => ({ slug: o.slug, label: null, fields: o.fields })),
+      ...kept.filter(
+        (k) => !outputs.some((o) => o.slug === k.slug && o.value === k.value)
+      ),
+    ];
+    if (sources.length) {
+      assignments = await wireFields(manifest, sources, P);
     } else {
       // First step: ask for each field by hand.
       const props = manifest.input_schema?.properties || {};
@@ -411,13 +413,13 @@ export async function buildWizard(opts = {}) {
     }
 
     const spec = `${tool.slug} ${assignments.map((a) => a.text).join(" ")}`.trim();
-    steps.push({ slug: tool.slug, spec, assignments });
+    steps.push({ slug: tool.slug, spec, assignments, label: null });
 
     console.log(chalk.gray(`\n  Running  ${spec}\n`));
     const started = Date.now();
     const result = await execute(
       tool.slug,
-      literalInput(assignments, outputs.length ? outputs[outputs.length - 1].value : undefined)
+      literalInput(assignments, outputs.length ? outputs[outputs.length - 1].value : undefined, scope)
     );
 
     if (!result.ok) {
@@ -438,6 +440,37 @@ export async function buildWizard(opts = {}) {
 
     outputs.push({ slug: tool.slug, value: result.result, fields });
 
+    // Keeping an output lets a later step read it again, which is the only way to
+    // carry two values forward without re-running the step that produced them.
+    if (fields.length) {
+      const keep = await P.confirm({
+        message: `Keep ${tool.slug}'s output for later steps?`,
+        default: false,
+      });
+      if (keep) {
+        const label = await P.input({
+          message: "  Call it",
+          default: defaultLabel(tool.slug, scope),
+        });
+        const name = String(label).trim();
+        if (name) {
+          if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+            console.log(chalk.yellow(`  "${name}" is not a usable label — ignored.`));
+          } else if (scope.has(name)) {
+            console.log(chalk.yellow(`  "${name}" is already used — ignored.`));
+          } else {
+            const last = steps[steps.length - 1];
+            if (last) {
+              last.label = name;
+              last.spec = `${last.spec} as=${name}`;
+            }
+            scope.set(name, result.result);
+            kept.push({ slug: tool.slug, label: name, fields, value: result.result });
+          }
+        }
+      }
+    }
+
     if (fields.length === 0) break;
     const more = await P.confirm({ message: "Send this output into another tool?", default: steps.length < 2 });
     if (!more) break;
@@ -479,7 +512,7 @@ export async function buildWizard(opts = {}) {
  * A reference that resolves to nothing is omitted rather than passed as
  * `undefined`, so schema validation reports the field by name.
  */
-function literalInput(assignments, upstream) {
+function literalInput(assignments, upstream, scope) {
   const input = {};
   for (const a of assignments) {
     const eq = a.text.indexOf("=");
@@ -488,7 +521,6 @@ function literalInput(assignments, upstream) {
     const raw = a.text.slice(eq + 1);
 
     if (raw.startsWith("$")) {
-      if (upstream === undefined) continue;
       let expr;
       try {
         expr = parseValueExpr(raw);
@@ -496,9 +528,19 @@ function literalInput(assignments, upstream) {
         continue;
       }
       if (expr.kind !== "connection" || !expr.accessors) continue;
+      // A leading segment naming a kept output wins over the previous step,
+      // matching how the engine resolves it.
+      let source = upstream;
+      let accessors = expr.accessors;
+      const labelled = scopeToLabel(expr.accessors, scope);
+      if (labelled) {
+        source = labelled.upstream;
+        accessors = labelled.accessors;
+      }
+      if (source === undefined) continue;
       let value;
       try {
-        value = resolveAccessors(upstream, expr.accessors);
+        value = resolveAccessors(source, accessors);
       } catch {
         continue;
       }
@@ -516,4 +558,4 @@ function literalInput(assignments, upstream) {
   return input;
 }
 
-export { transformNames, parsePath, rankTransforms };
+export { transformNames, parsePath, rankTransforms, defaultLabel };