@nexusbloom/cli 0.9.3 → 0.9.5

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

package/package.json

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

package/src/abbr.js

@@ -1,13 +1,7 @@
 /**
  * abbr.js — `nxb abbr` command.
  *
- * Paginated abbreviation view.
- *
- *   nxb abbr                 — interactive pagination (20/page)
- *   nxb abbr ip              — filter by query (matches slug, abbr, or name)
- *   nxb abbr -s ip           — same, explicit flag
- *   nxb abbr --json          — raw JSON
- *   nxb abbr --no-interactive— single dump
+ * Paginated abbreviation view. Flags are declared in index.js.
  */
 
 import chalk from "chalk";

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/index.js

@@ -1,27 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * NexusBloom CLI (nxb)
+ * NexusBloom CLI (nxb) — command wiring.
  *
- * Usage:
- *   nxb list                           — List available tools (interactive pagination)
- *   nxb list -s <query>                — Filter + paginate
- *   nxb search <query>                 — Search tools
- *   nxb run <slug> [args...]           — Execute a tool (remote API)
- *   nxb run <slug> --input '{}'        — Execute with inline JSON input
- *   nxb run <slug> --file input.json   — Execute with file input
- *   nxb run <slug> --local             — Execute coreLogic locally (cached)
- *   nxb run                            — Interactive: select tool → pick inputs → auto-build command
- *   nxb run -s <query>                 — Filter the tool picker (non-TTY: print the list)
- *   nxb info <slug>                    — Show tool schema
- *   nxb abbr [-s <query>]              — Show tool abbreviations (paginated)
- *   nxb transform <slug>               — Pipe stdin through a tool
- *   nxb config set <key> [value]       — Set config (interactive if value omitted)
- *   nxb config get [key]               — Get config (secrets redacted)
- *   nxb cache clear                    — Clear local tool cache
- *   nxb cache list                     — List cached tools
- *   nxb cache path                     — Print where config/cache live
- *   nxb json --template <slug>         — Create JSON input for tools
+ * Commands are declared with commander below, and `--help` is generated from
+ * those declarations. A hand-maintained usage list in this header was always
+ * going to drift from the code, so there isn't one; README.md carries the
+ * task-oriented examples.
  */
 
 import { program } from "commander";

package/src/list.js

@@ -1,12 +1,9 @@
 /**
  * list.js — `nxb list` command.
  *
- * Paginated tool listing. Long lists are always paired with a search option.
- *
- *   nxb list                  — interactive pagination (20/page)
- *   nxb list -s ssl           — filter + paginate
- *   nxb list --json           — raw JSON
- *   nxb list --no-interactive — single dump
+ * Paginated tool listing. Long lists are always paired with a search option;
+ * `--json` and the other flags are declared in index.js, which is also where
+ * `--help` reads them from.
  */
 
 import chalk from "chalk";

package/src/run.js

@@ -2,11 +2,11 @@
  * run.js — `nxb run` command.
  *
  * Two modes:
- *   1. Direct:  nxb run <slug> [key=value ...] [--input json] [--file path] [--local]
- *   2. Interactive: nxb run (no slug) → select tool → pick inputs → auto-build & execute
+ *   1. Direct:       nxb run <slug> [key=value ...] [--input json] [--file path] [--local]
+ *   2. Interactive:  nxb run  → select tool → pick inputs → auto-build & execute
  *
- * Imports execution logic from the original monolithic index.js but adds
- * inquirer-driven field prompting for the interactive path.
+ * The interactive path is only entered when no slug and no input were supplied,
+ * otherwise a scripted call would block on a prompt it never sees.
  */
 
 import fs from "fs";

package/src/tools.js

@@ -1,29 +1,16 @@
 /**
- * tools.js — Centralised tool catalogue for the nxb CLI.
+ * tools.js — Tool catalogue resolution and config access.
  *
  * Resolution order for the *tool list*:
- *   1. Cached snapshot  (`.cache/tools-list.json`) — always written on a
- *      successful fetch so subsequent `list` / `abbr` calls are offline-fast.
- *   2. Live API          (`/api/tools`)
+ *   1. Cached snapshot (`$XDG_CACHE_HOME/nexusbloom/tools-list.json`) — written
+ *      on every successful fetch, so `list` / `abbr` stay fast and work offline
+ *   2. Live API (`/api/tools`)
  *   3. Supabase fallback (`/rest/v1/tools` + `/rest/v1/community_tools`)
- *   4. Local filesystem scan (`src/tools/<slug>/v2.js`)
+ *   4. Local filesystem scan — see `LOCAL_TOOL_DIRS` for the search roots
  *
- * Resolution order for a *single tool's source* (for `--local` execution):
- *   1. Local filesystem  → 2. cache (`tools/<slug>.json`) → 3. API/Supabase
- *
- * Exports:
- *   loadConfig / saveConfig / configGet / configSet / redactedConfig
- *   fetchTools()              — resolves list (cache-first on network failure)
- *   refreshTools()            — force a fresh fetch + persist to cache
- *   fetchToolSource(slug)     — { manifest, coreLogicSource }
- *   filterTools / rankTools   — shared search used by list / search / abbr / run
- *   isValidSlug / normalizeSlug
- *   scanLocalTools()
- *   findLocalTool(slug)
- *   generateAbbreviations(slugs)
- *   resolveToolSlug(slug, tools?)
- *   getSupabaseKey / getSupabaseUrl / supabaseHeaders
- *   API_BASE
+ * Resolution order for a *single tool's source* (for `--local` execution) is
+ * the mirror image: local filesystem, then cache, then API/Supabase. Local wins
+ * because a developer running `--local` is iterating on that file right now.
  */
 
 import fs from "fs";
@@ -446,7 +433,6 @@ export async function fetchToolSource(rawSlug) {
     const source = fs.readFileSync(localPath, "utf-8");
     const manifest = extractManifest(source, { trusted: true });
     if (manifest) {
-      // Refresh cache from local source
       fs.writeFileSync(cacheFile, JSON.stringify({ manifest, coreLogicSource: source, cachedAt: new Date().toISOString() }), "utf-8");
       return { manifest, coreLogicSource: source, source: "local" };
     }

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";
@@ -203,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}` });
+  }
+
+  return assignments;
+}
 
-    if (compat.level === "cast" && compat.suggestion) {
-      const use = await P.confirm({
-        message: `${field} expects ${typeLabel(targetTypes)} — apply ${chalk.cyan(compat.suggestion)}?`,
-        default: true,
+/**
+ * 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) {
@@ -391,4 +516,4 @@ function literalInput(assignments, upstream) {
   return input;
 }
 
-export { transformNames, parsePath };
+export { transformNames, parsePath, rankTransforms };