@nexusbloom/cli 0.9.2 → 0.9.4

package/README.md

@@ -209,6 +209,33 @@ $ 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:
+
+```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()
+```
+
+This produces the same `$path|transform()` syntax you can write by hand. Two
+constraints come from the parser, and the builder refuses bad input up front
+rather than emitting a spec that will not run:
+
+- **No spaces anywhere in a connection.** `$items|join(", ")` is rejected — use
+  `join(",")`. The parser cannot distinguish a space inside a quoted argument
+  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.
+
 ### Saved pipelines
 
 ```bash
@@ -323,17 +350,6 @@ removed rather than resolved. Relative imports like `import { helper } from
 `export const coreLogic = async () => {}` and plain `function coreLogic` are all
 supported.
 
-## Development
-
-```bash
-npm test              # 500+ tests, no network required
-npm run test:coverage # with a coverage report
-npm run test:watch    # re-run on change
-```
-
-The suite runs fully offline and is isolated from your real config, API key and
-network — both properties are enforced by guard tests, not assumed.
-
 ## Security Notes
 
 - No API keys or Supabase keys are shipped inside the package.

package/package.json

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

package/src/commands.js

@@ -23,7 +23,7 @@ import {
   runPipeline,
 } from "./pipe.js";
 import { inferType, schemaTypes, typeLabel } from "./types.js";
-import { MISSING, getPath, preview, transformNames, parsePath, formatPath } from "./values.js";
+import { MISSING, getPath, preview, transformNames, parsePath, formatPath, TRANSFORM_GROUPS } from "./values.js";
 import { buildWizard } from "./wizard.js";
 
 /** Shared manifest/tool lookup used by the plan, the runner and the wizard. */
@@ -150,17 +150,13 @@ export function listTransforms(jsonMode) {
     return;
   }
   console.log(chalk.bold("\n  Connection transforms\n"));
-  const rows = [
-    ["len / count / words / lines / chars", "size of a string, array or object"],
-    ["first / last / get(i) / slice(a,b)", "reduce an array to a single value"],
-    ["join(sep) / split(sep) / reverse / sort(key)", "reshape collections"],
-    ["keys / values / pick(field)", "reach into an object"],
-    ["upper / lower / trim / replace(a,b) / pad(n)", "edit text"],
-    ["int() / float() / num / str / bool()", "change type — required for casts"],
-    ["json / unjson", "serialise / parse"],
-    ["default(v)", "supply a value when the path is missing"],
-  ];
-  for (const [a, b] of rows) console.log(`  ${chalk.cyan(a.padEnd(42))} ${chalk.dim(b)}`);
+  // Rendered from the shared catalogue so the list and the wizard's picker can
+  // never describe the same transform differently. The column is sized to the
+  // longest heading, which is wider than a fixed pad and left the docs ragged.
+  const width = Math.max(...TRANSFORM_GROUPS.map((g) => g.label.length)) + 2;
+  for (const group of TRANSFORM_GROUPS) {
+    console.log(`  ${chalk.cyan(group.label.padEnd(width))} ${chalk.dim(group.doc)}`);
+  }
   console.log(chalk.dim("\n  Use:  key=$path|transform        (no spaces around |)\n"));
   return { ok: true };
 }

package/src/values.js

@@ -223,6 +223,127 @@ export function transformNames() {
   return Object.keys(TRANSFORMS).sort();
 }
 
+/**
+ * One-line description per transform, for the wizard's picker.
+ *
+ * These live beside the implementations rather than in the UI so that adding a
+ * transform and describing it are the same edit — a picker entry with no
+ * description reads as a mystery, and a description with no entry is worse.
+ */
+export const TRANSFORM_DOCS = {
+  len: "length of a string, array or object",
+  count: "same as len — size of an array or string",
+  words: "number of whitespace-separated words",
+  lines: "number of lines",
+  chars: "number of characters",
+  first: "first element of an array",
+  last: "last element of an array",
+  get: "element at an index",
+  slice: "a range of an array or string",
+  join: "array to a string, with a separator",
+  keys: "an object's keys, as an array",
+  values: "an object's values, as an array",
+  reverse: "reverse an array",
+  sort: "sort an array, optionally by field",
+  upper: "UPPERCASE",
+  lower: "lowercase",
+  trim: "strip surrounding whitespace",
+  replace: "replace every occurrence of a substring",
+  pad: "pad the start to a width",
+  split: "string to an array on a separator",
+  str: "to string",
+  int: "to integer",
+  float: "to number",
+  num: "to number",
+  bool: "to true/false",
+  json: "serialise to a JSON string",
+  unjson: "parse a JSON string",
+  pick: "one field out of an object",
+  default: "value to use when the path is missing",
+};
+
+/**
+ * The catalogue grouped by purpose, for `nxb pipe --transforms`.
+ *
+ * `label` is the heading as a user reads it — arg hints and all — so it is
+ * written out rather than derived from `TRANSFORM_ARITY` (which would render
+ * `get()` where the heading wants `get(i)`).
+ */
+export const TRANSFORM_GROUPS = [
+  { label: "len / count / words / lines / chars", doc: "size of a string, array or object",
+    names: ["len", "count", "words", "lines", "chars"] },
+  { label: "first / last / get(i) / slice(a,b)", doc: "reduce an array to a single value",
+    names: ["first", "last", "get", "slice"] },
+  { label: "join(sep) / split(sep) / reverse / sort(key)", doc: "reshape collections",
+    names: ["join", "split", "reverse", "sort"] },
+  { label: "keys / values / pick(field)", doc: "reach into an object",
+    names: ["keys", "values", "pick"] },
+  { label: "upper / lower / trim / replace(a,b) / pad(n)", doc: "edit text",
+    names: ["upper", "lower", "trim", "replace", "pad"] },
+  { label: "int() / float() / num / str / bool()", doc: "change type — required for casts",
+    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"] },
+];
+
+/**
+ * How many arguments a transform takes, excluding the value itself.
+ * @returns {number} 0 for transforms callable with no argument
+ */
+export function transformArgCount(name) {
+  const arity = TRANSFORM_ARITY[name];
+  return arity === undefined ? 0 : Math.max(0, arity - 1);
+}
+
+/**
+ * Render one literal as it must appear inside a pipeline spec.
+ *
+ * Bare words are left alone (`hello`, `2024-01-01`); anything that could be
+ * misread — a space, a comma, a quote — is JSON-quoted so `parseValueExpr`'s
+ * quote-aware splitter sees it as one argument.
+ */
+export function formatArg(value) {
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value === null || value === undefined) return "";
+  const s = String(value);
+  if (s === "") return '""';
+  if (/^[\w.@/+-]+$/.test(s)) return s;
+  return JSON.stringify(s);
+}
+
+/**
+ * Render a transform call: `len()`, `get(0)`, `join(",")`.
+ *
+ * Always emits parens, even with no arguments, so the result reads as a call
+ * and round-trips through `parseTransform` unchanged.
+ */
+export function formatTransformCall(name, args = []) {
+  return `|${name}(${(args || []).map(formatArg).join(",")})`;
+}
+
+/**
+ * Reject an argument the parser cannot accept.
+ *
+ * `parseValueExpr` rejects whitespace anywhere in an expression — it cannot
+ * tell a separator from a space inside a quoted argument, so `$x|join(", ")` is
+ * refused. Better to say so at the prompt than to emit a spec that fails to
+ * parse after the pipeline is already built.
+ *
+ * @returns {string|null} an error message, or null when the arg is usable
+ */
+export function validateTransformArg(raw) {
+  const s = String(raw ?? "");
+  if (/\s/.test(s)) {
+    return "arguments cannot contain spaces — the pipeline syntax has none. Try a symbol like \"-\" or \"%20\".";
+  }
+  if (s.includes("|")) {
+    return "arguments cannot contain \"|\" — it separates steps in a pipeline.";
+  }
+  return null;
+}
+
 /**
  * Apply a chain of transforms to a value.
  * @param {any} value

package/src/wizard.js

@@ -33,7 +33,18 @@ 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, MISSING } from "./values.js";
+import {
+  formatPath,
+  parsePath,
+  preview,
+  transformNames,
+  transformArgCount,
+  formatTransformCall,
+  validateTransformArg,
+  TRANSFORM_DOCS,
+  TRANSFORMS,
+  MISSING,
+} from "./values.js";
 import { parseValueExpr, resolveAccessors } from "./pipe.js";
 import { isInteractive } from "./ui.js";
 import { renderHeader } from "./ui.js";
@@ -97,8 +108,16 @@ function renderObservedOutput(fields) {
 
 // ─── Prompts ─────────────────────────────────────────────────────────────────
 
+/**
+ * Ask for a tool to add as the next step.
+ *
+ * A tool may be chosen more than once: the pipeline engine addresses steps
+ * positionally, so `base64-tool … | base64-tool text=$result action=decode`
+ * is a legal round-trip. (It was verified working before this restriction was
+ * lifted.) `exclude` remains for callers that genuinely need a subset.
+ */
 async function pickTool(tools, exclude = [], P = defaultPrompts) {
-  const pool = tools.filter((t) => !exclude.includes(t.slug));
+  const pool = exclude.length ? tools.filter((t) => !exclude.includes(t.slug)) : tools;
   const source = async (term) => {
     const hits = term ? rankTools(pool, term) : pool;
     return hits.slice(0, 50).map((t) => ({
@@ -195,20 +214,134 @@ async function wireFields(manifest, prevSlug, prevFields, P = defaultPrompts) {
     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 = "";
+    // 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 })
+      : "";
+
+    assignments.push({ kind: "wire", text: `${field}=$${choice.path}${chain}` });
+  }
 
-    if (compat.level === "cast" && compat.suggestion) {
-      const use = await P.confirm({
-        message: `${field} expects ${typeLabel(targetTypes)} — apply ${chalk.cyan(compat.suggestion)}?`,
-        default: true,
+  return assignments;
+}
+
+/**
+ * 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.
+ *
+ * The returned string is appended to `$path`, so it already carries its own
+ * leading `|`.
+ */
+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 (use) transform = `|${compat.suggestion}`;
+      if (!more) break;
+      const built = await promptOneTransform(P);
+      if (!built) break;
+      chain += built;
     }
+    return chain;
+  }
 
-    assignments.push({ kind: "wire", text: `${field}=$${choice.path}${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) return await buildSuggestedTransform(compat.suggestion, P);
   }
 
-  return assignments;
+  return "";
+}
+
+/**
+ * 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.
+ */
+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);
+
+  const args = [];
+  for (let i = 0; i < Math.max(1, transformArgCount(name)); i++) {
+    args.push(
+      await P.input({
+        message: `${name}()  argument ${i + 1}`,
+        validate: (v) => validateTransformArg(v),
+      })
+    );
+  }
+  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);
+  }
+
+  return formatTransformCall(name, args);
+}
+
+/** Rank transforms by name and description, so "array" finds `join`. */
+function rankTransforms(term) {
+  if (!term) return [];
+  const t = String(term).toLowerCase();
+  return transformNames().filter(
+    (n) => n.includes(t) || (TRANSFORM_DOCS[n] || "").toLowerCase().includes(t)
+  );
 }
 
 function formatLiteral(value) {
@@ -246,7 +379,6 @@ export async function buildWizard(opts = {}) {
 
   const steps = [];
   const outputs = [];
-  const usedSlugs = [];
 
   for (;;) {
     renderHeader(
@@ -254,7 +386,7 @@ export async function buildWizard(opts = {}) {
       { subtitle: steps.length ? "Pick the next tool to feed" : "Start with any tool" }
     );
 
-    const tool = await pickTool(tools, usedSlugs, P);
+    const tool = await pickTool(tools, [], P);
     if (!tool) break;
 
     const info = await getTool(tool.slug);
@@ -280,7 +412,6 @@ export async function buildWizard(opts = {}) {
 
     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();
@@ -294,7 +425,6 @@ export async function buildWizard(opts = {}) {
       // 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;
@@ -386,4 +516,4 @@ function literalInput(assignments, upstream) {
   return input;
 }
 
-export { transformNames, parsePath };
+export { transformNames, parsePath, rankTransforms };