@nexusbloom/cli 0.9.5 → 0.9.6

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.6",
   "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/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,68 @@ 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.select({
+    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.select({
+      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,
+    ...hits.slice(0, 50).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 +308,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 +334,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 +368,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 +390,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 +410,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 +437,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 +509,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 +518,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 +525,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 +555,4 @@ function literalInput(assignments, upstream) {
   return input;
 }
 
-export { transformNames, parsePath, rankTransforms };
+export { transformNames, parsePath, rankTransforms, defaultLabel };