@nexusbloom/cli 0.9.6 → 0.9.8

package/package.json

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

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,226 @@ 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;
+  },
+  // These collapse an *array*; they do not compare against a bound. `clamp(lo,hi)`
+  // is the one that takes bounds. Ignoring a second argument silently was the
+  // reason `min(120, 60)` returned 120 instead of erroring, so it now returns the
+  // value untouched rather than pretending to have clamped anything.
+  min: (v, ...ignored) =>
+    ignored.length
+      ? v
+      : Array.isArray(v) && v.length
+        ? Math.min(...v.filter((n) => typeof n === "number"))
+        : v,
+  max: (v, ...ignored) =>
+    ignored.length
+      ? 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 +473,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 +530,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 (to bound a single number use clamp)",
+  max: "largest number in an array (to bound a single number use clamp)",
+  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 +619,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 +709,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

@@ -246,7 +246,7 @@ async function wireFields(manifest, sources, P = defaultPrompts) {
  * The returned string is appended to `$path`, so it carries its own `|`.
  */
 async function promptTransformChain(field, P) {
-  const picked = await P.select({
+  const picked = await P.search({
     message: `${field}: transform${chalk.gray("  (optional)")}`,
     source: (term) => transformChoices(term, { withNone: true }),
     pageSize: 15,
@@ -262,7 +262,7 @@ async function promptTransformChain(field, P) {
       default: false,
     });
     if (!more) break;
-    const next = await P.select({
+    const next = await P.search({
       message: `${field}: another transform`,
       source: (term) => transformChoices(term, { withNone: true }),
       pageSize: 15,
@@ -284,7 +284,10 @@ function transformChoices(term, { withNone = false } = {}) {
   const hits = term ? rankTransforms(term) : transformNames();
   return [
     ...skip,
-    ...hits.slice(0, 50).map((n) => ({
+    // 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] || "")}`,
     })),