@nexusbloom/cli 0.3.4 → 0.8.0

package/src/pipe.js

@@ -0,0 +1,709 @@
+/**
+ * pipe.js — Compose tools into a pipeline.
+ *
+ *   nxb pipe frequency-analyzer text=@in type=word \
+ *     '| data-generator count=$total_words format=json' \
+ *     '| base64-tool text=$data|first.email action=$mode|upper'
+ *
+ * Syntax
+ *   step        `slug key=value key2=value`
+ *   separator   a leading `|` marks a new step; each step is one shell argument
+ *   connection  `key=$path` reads from the previous step's output
+ *   whole value `key=$` passes the entire previous output
+ *   transform   `$path|len`, `$max|int`, `$data|first` — chained left to right
+ *   stdin       `key=@in` receives the pipeline's standard input
+ *
+ * Two phases, deliberately separated:
+ *   1. buildPlan()  resolves every connection against the declared schemas and
+ *                   reports type problems *before* anything runs.
+ *   2. runPipeline() executes, re-checking types against real values, because
+ *                   declared schemas can be wrong or missing.
+ */
+
+import chalk from "chalk";
+
+import {
+  MISSING,
+  applyTransforms,
+  formatPath,
+  getPath,
+  parsePath,
+  preview,
+  TRANSFORMS,
+  TRANSFORM_ARITY,
+} from "./values.js";
+import { compatibility, inferType, schemaTypes, typeLabel, validateInput } from "./types.js";
+
+// ─── Parsing ─────────────────────────────────────────────────────────────────
+
+/** Parse one transform segment: `first`, `int(5)`, `slice(0,3)`, `default("x")`. */
+function parseTransform(segment) {
+  const m = segment.match(/^([a-z_][a-z0-9_]*)\s*(?:\(([\s\S]*)\))?$/i);
+  if (!m) throw new Error(`Invalid transform "${segment}"`);
+  const name = m[1];
+  if (!TRANSFORMS[name]) {
+    throw new Error(`Unknown transform "${name}"`);
+  }
+  let args = [];
+  const rawArgs = (m[2] || "").trim();
+  if (rawArgs) {
+    args = splitArgs(rawArgs).map(coerceArg);
+  }
+  const needed = TRANSFORM_ARITY[name];
+  if (needed !== undefined && args.length < needed - 1) {
+    throw new Error(`Transform "${name}" needs ${needed - 1} argument(s)`);
+  }
+  return { name, args };
+}
+
+/** Split `a,"b,c",3` respecting quotes. */
+function splitArgs(str) {
+  const out = [];
+  let cur = "";
+  let quote = null;
+  for (const ch of str) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === ",") {
+      out.push(cur.trim());
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim() !== "" || out.length) out.push(cur.trim());
+  return out;
+}
+
+function coerceArg(raw) {
+  const s = String(raw).trim();
+  if (s === "") return "";
+  if (s === "true") return true;
+  if (s === "false") return false;
+  if (s === "null") return null;
+  if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+  return s;
+}
+
+/** Split a step's spec into slug + argument tokens, respecting quotes. */
+function tokenize(spec) {
+  const tokens = [];
+  let cur = "";
+  let quote = null;
+  let depth = 0;
+  for (const ch of spec) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "(") depth++;
+    if (ch === ")") depth = Math.max(0, depth - 1);
+    if (ch === " " && depth === 0) {
+      if (cur) tokens.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur) tokens.push(cur);
+  return tokens;
+}
+
+/**
+ * Parse the expression on the right of `key=`.
+ *
+ * The `$` form interleaves path access and transforms so that both
+ * `$data[0].email` and `$data|first.email` work:
+ *
+ *   accessors: [ {path:"data"}, {transform:"first"}, {path:".email"} ]
+ *
+ * A segment is treated as a transform when it parses as `name` or `name(args)`
+ * and that name is in the transform library; anything else continues the path.
+ *
+ * @returns {{kind:"stdin"|"connection"|"literal", headPath?: string,
+ *            accessors?: Array, chain?: Array, literal?: any}}
+ */
+function parseValueExpr(expr) {
+  const raw = String(expr ?? "");
+
+  if (raw === "@in" || raw === "@stdin") return { kind: "stdin" };
+
+  if (!raw.startsWith("$")) return { kind: "literal", literal: coerceArg(raw) };
+
+  if (/\s/.test(raw)) {
+    throw new Error(`"${raw}" — write transforms without spaces (${raw.replace(/\s+/g, "")})`);
+  }
+
+  // Split into `|`-delimited segments, ignoring pipes inside parentheses.
+  const segments = [];
+  let cur = "";
+  let depth = 0;
+  for (const ch of raw) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth = Math.max(0, depth - 1);
+    if (ch === "|" && depth === 0) {
+      segments.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  segments.push(cur);
+
+  const head = segments[0];
+  if (head !== "$" && !head.startsWith("$")) {
+    throw new Error(`Transform chain must start with $ (got "${raw}")`);
+  }
+  if (head.includes("|")) throw new Error(`Invalid path "${head}"`);
+
+  const accessors = [];
+  let headPath = "";
+
+  segments.forEach((seg, idx) => {
+    if (idx === 0) {
+      headPath = seg.slice(1);
+      accessors.push({ op: "path", path: headPath });
+      return;
+    }
+
+    // After the head, a segment is a path when it is explicitly written as one
+    // (a leading `.`, a `[index]`, or a bare index). Anything else must be a
+    // transform — guessing between the two would turn a typo like
+    // `$text|lenh` into a silent field lookup that fails much later.
+    if (seg.startsWith(".") || seg.startsWith("[") || /^\d+$/.test(seg)) {
+      accessors.push({ op: "path", path: seg });
+      return;
+    }
+
+    const m = seg.match(/^([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?/);
+    if (seg === "") {
+      throw new Error(
+        `Empty stage in "${raw}" — write transforms without spaces, e.g. $x|len not $x| len.`
+      );
+    }
+    const name = m?.[1];
+    if (!name || !Object.hasOwn(TRANSFORMS, name)) {
+      throw new Error(
+        `Unknown transform "${seg}". For a field, write it with a leading dot ($x.${seg}); for the list, run \`nxb pipe --transforms\`.`
+      );
+    }
+
+    // Anything glued to the call continues as a path, so `$data|first.email`
+    // is first(), then `.email`.
+    const rest = seg.slice(m[0].length);
+    accessors.push({ op: "transform", ...parseTransform(m[0]) });
+    if (rest) accessors.push({ op: "path", path: rest });
+  });
+
+  // Validate every path eagerly so errors surface while parsing, not mid-run.
+  for (const acc of accessors) {
+    if (acc.op === "path") parsePath(acc.path.replace(/^\./, ""));
+  }
+
+  return {
+    kind: "connection",
+    headPath,
+    accessors,
+    // Retained for display: the transform chain in source order.
+    chain: accessors.filter((a) => a.op === "transform"),
+  };
+}
+
+
+/**
+ * Resolve a connection against an upstream value.
+ * @returns {value|typeof MISSING}
+ */
+export function resolveAccessors(upstream, accessors) {
+  let cur = upstream;
+  for (const acc of accessors) {
+    if (acc.op === "path") {
+      // A missing value keeps flowing, so a later |default(...) can rescue it.
+      if (cur === MISSING) continue;
+      cur = getPath(cur, acc.path.replace(/^\./, ""));
+    } else {
+      cur = applyTransforms(cur, [{ name: acc.name, args: acc.args }]);
+    }
+  }
+  return cur;
+}
+
+/**
+ * Split a pipeline into step chunks on `|`.
+ *
+ * `|` is ambiguous — it also separates transform stages (`$text|len`). The
+ * disambiguator is the token that follows: a known transform name means a
+ * transform pipe, anything else means a step separator. Write transforms
+ * without spaces around the pipe (`$text|len`, not `$text | len`).
+ */
+function splitSteps(text) {
+  const chunks = [];
+  let cur = "";
+  let quote = null;
+  let depth = 0;
+  let inValue = false; // inside a `key=$...` token, where `|` always means transform
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+
+    if (quote) {
+      if (ch === quote) quote = null;
+      cur += ch;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      cur += ch;
+      continue;
+    }
+
+    // `key=$...` opens a connection token; whitespace closes it.
+    if (ch === "=" && text[i + 1] === "$") inValue = true;
+    else if (ch === " " || ch === "\t" || ch === "\n") inValue = false;
+
+    if (ch === "(") depth++;
+    if (ch === ")") depth = Math.max(0, depth - 1);
+
+    if (ch === "|" && depth === 0) {
+      // Inside a connection, or when a known transform follows, this pipe
+      // belongs to the transform chain rather than to the step list.
+      if (inValue || isKnownTransformWord(text.slice(i + 1))) {
+        cur += ch;
+        continue;
+      }
+      chunks.push(cur);
+      cur = "";
+      continue;
+    }
+
+    cur += ch;
+  }
+
+  if (cur.trim()) chunks.push(cur);
+  return chunks;
+}
+
+function isKnownTransformWord(rest) {
+  const word = (rest.match(/^\s*([a-zA-Z_][a-zA-Z0-9_]*)/) || [])[1];
+  return word !== undefined && Object.hasOwn(TRANSFORMS, word);
+}
+
+/**
+ * Parse a full pipeline string (or argv array) into steps.
+ * Accepts both `a x=1 | b y=$x` as one string and as separate arguments.
+ *
+ * @returns {Array<{slug: string, inputs: Array<{field: string, expr: object}>}>}
+ */
+export function parsePipeline(spec) {
+  const text = Array.isArray(spec) ? spec.join(" ") : String(spec);
+  const chunks = splitSteps(text);
+
+  const steps = [];
+  for (const chunk of chunks) {
+    const spec = chunk.trim();
+    if (!spec) continue;
+    const tokens = tokenize(spec);
+    if (!tokens.length) continue;
+
+    const slug = tokens[0];
+    if (!/^[a-zA-Z0-9._-]+$/.test(slug)) {
+      throw new Error(`Invalid tool slug "${slug}"`);
+    }
+
+    const inputs = [];
+    for (const token of tokens.slice(1)) {
+      const eq = token.indexOf("=");
+      if (eq === -1) {
+        throw new Error(`Expected key=value in "${spec}", got "${token}"`);
+      }
+      const field = token.slice(0, eq);
+      const valueExpr = token.slice(eq + 1);
+      if (!field) throw new Error(`Missing field name in "${token}"`);
+      const expr = parseValueExpr(valueExpr);
+      const exprText = expr.kind === "literal" ? "" : `$${expr.headPath ?? ""}`;
+      inputs.push({ field, expr, exprText });
+    }
+    steps.push({ slug, inputs, raw: spec });
+  }
+
+  if (!steps.length) throw new Error("Empty pipeline.");
+  return steps;
+}
+
+// ─── Plan ────────────────────────────────────────────────────────────────────
+
+/**
+ * Build the wiring plan by resolving every connection against declared schemas.
+ *
+ * @param {Array} steps        from parsePipeline()
+ * @param {(slug) => Promise<{manifest: object}|null>} getManifest
+ * @returns {Promise<{steps: Array, issues: Array, ok: boolean}>}
+ */
+export async function buildPlan(steps, getManifest) {
+  const planned = [];
+  const issues = [];
+  const produced = new Map(); // slug -> output field names it declares
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const entry = { ...step, index: i, manifest: null, fields: [] };
+
+    let info = null;
+    try {
+      info = await getManifest(step.slug);
+    } catch (err) {
+      issues.push({ step: i, level: "error", message: `Could not load "${step.slug}": ${err.message}` });
+    }
+
+    if (!info?.manifest) {
+      issues.push({ step: i, level: "error", message: `Tool "${step.slug}" not found or has no manifest.` });
+      planned.push(entry);
+      continue;
+    }
+
+    entry.manifest = info.manifest;
+    const props = info.manifest.input_schema?.properties || {};
+    const outProps = info.manifest.output_schema?.properties || {};
+    entry.outputs = Object.keys(outProps);
+    produced.set(step.slug, outProps);
+
+    for (const input of step.inputs) {
+      const prop = props[input.field];
+      const field = {
+        ...input,
+        targetTypes: schemaTypes(prop),
+        targetEnum: Array.isArray(prop?.enum) ? prop.enum : null,
+        knownField: Boolean(prop),
+        verdict: "literal",
+      };
+
+      if (!prop) {
+        field.verdict = "unknown-field";
+        issues.push({
+          step: i,
+          level: "warn",
+          message: `"${step.slug}" has no input field "${input.field}" — it will still be sent.`,
+        });
+      }
+
+      if (input.expr.kind === "connection") {
+        const prev = i > 0 ? steps[i - 1] : null;
+        if (!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;
+
+          field.source = {
+            slug: prev.slug,
+            path: input.expr.headPath,
+            pathLabel: formatPath(headSegments),
+          };
+          field.sourceTypes = schemaTypes(prevProp);
+          field.sourceKnown = known;
+
+          // Walk the accessors to work out the type that actually arrives.
+          field.resultTypes = simulateTypes(input.expr.accessors, field.sourceTypes);
+          // A path used *after* a transform cannot be typed from the schema.
+          if (!known || headSegments.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.`,
+            });
+          } else if (field.targetTypes.length && field.resultTypes.length) {
+            const compat = compatibility(field.resultTypes[0], field.targetTypes);
+            field.compat = compat;
+            if (compat.level === "cast") {
+              field.verdict = "needs-cast";
+              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}`,
+              });
+            } 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}).`,
+              });
+            } 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}.` });
+            } else {
+              field.verdict = "ok";
+            }
+          } else {
+            field.verdict = "ok";
+          }
+        }
+      }
+
+      entry.fields.push(field);
+    }
+
+    planned.push(entry);
+  }
+
+  const ok = !issues.some((x) => x.level === "error");
+  return { steps: planned, issues, ok };
+}
+
+/** Representative values used to reason about a transform's return type. */
+const TYPE_SAMPLE = {
+  string: "sample text",
+  integer: 42,
+  number: 4.2,
+  boolean: true,
+  array: ["a", "b"],
+  object: { a: 1 },
+};
+
+/**
+ * Walk accessors using representative values to infer the type that will
+ * arrive at the target field.
+ *
+ * A path used *after* a transform cannot be resolved from a schema, so it is
+ * reported as unknown and left to the runtime check — which is the honest
+ * answer rather than a confident guess.
+ */
+function simulateTypes(accessors, sourceTypes) {
+  const source = sourceTypes?.[0];
+  if (!source || !TYPE_SAMPLE[source]) return [];
+
+  let cur = TYPE_SAMPLE[source];
+
+  for (let i = 0; i < accessors.length; i++) {
+    const acc = accessors[i];
+    if (acc.op === "path") {
+      // The head path *is* the declared source field, so it adds no
+      // uncertainty. Any later path step descends into a shape the schema
+      // does not describe, so we stop guessing and defer to runtime.
+      if (i === 0) continue;
+      return [];
+    }
+    try {
+      const next = applyTransforms(cur, [{ name: acc.name, args: acc.args }]);
+      if (next === MISSING) return [];
+      cur = next;
+    } catch {
+      return [];
+    }
+  }
+
+  const t = inferType(cur);
+  if (t === "integer") return ["integer", "number"];
+  return [t];
+}
+
+/**
+ * Run a planned pipeline.
+ *
+ * @param {object} opts
+ * @param {Array}  opts.steps      planned steps from buildPlan()
+ * @param {Function} opts.getTool  (slug) => { manifest, coreLogicSource }
+ * @param {Function} opts.execute  ({ slug, source, input, manifest, local }) => result
+ * @param {any}    opts.stdin      value for `@in`
+ * @param {number} [opts.from]     1-based step to start from (replay)
+ * @param {Function} [opts.onStep] progress callback
+ */
+export async function runPipeline({
+  steps,
+  getTool,
+  execute,
+  stdin = null,
+  from = 1,
+  onStep = () => {},
+}) {
+  const outputs = new Array(steps.length).fill(undefined);
+  const logs = [];
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+
+    // Replay: reuse a recorded output instead of re-running the step.
+    if (i + 1 < from && outputs[i] !== undefined) continue;
+
+    const input = {};
+    const resolvedInputs = {};
+
+    for (const field of step.fields) {
+      const { field: name, expr } = field;
+
+      if (expr.kind === "literal") {
+        input[name] = expr.literal;
+        resolvedInputs[name] = { value: expr.literal, from: "literal" };
+        continue;
+      }
+
+      if (expr.kind === "stdin") {
+        input[name] = stdin;
+        resolvedInputs[name] = { value: stdin, from: "@in" };
+        continue;
+      }
+
+      const upstream = outputs[i - 1];
+      if (upstream === undefined) {
+        throw new PipeError(`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)"}`;
+
+      // A connection that resolves to nothing is always an error: silently
+      // sending `undefined` hides the broken wire behind whatever the tool
+      // does with a missing field. `default(...)` is the explicit opt-in.
+      if (value === MISSING) {
+        const hasFallback = expr.accessors.some((a) => a.op === "transform" && a.name === "default");
+        if (!hasFallback) {
+          throw new PipeError(
+            `Step ${i + 1}: ${fromLabel} produced no value for ${step.slug}.${name}. ` +
+              `Check the field exists, or add |default(...) to continue anyway.`
+          );
+        }
+      }
+
+      input[name] = value === MISSING ? undefined : value;
+      resolvedInputs[name] = { value, from: fromLabel };
+    }
+
+    // Runtime type check against the real manifest — catches schema drift that
+    // the static plan cannot see.
+    const problems = validateInput(input, step.manifest?.input_schema);
+    if (problems.length) {
+      const detail = problems
+        .map((p) => `${p.field}: ${p.error}${p.suggestion ? ` (${p.suggestion})` : ""}`)
+        .join("; ");
+      throw new PipeError(`Step ${i + 1} (${step.slug}) input invalid — ${detail}`);
+    }
+
+    onStep({ phase: "start", index: i, step, input, resolvedInputs });
+
+    const tool = await getTool(step.slug);
+    const result = await execute({
+      slug: step.slug,
+      source: tool?.coreLogicSource,
+      manifest: step.manifest,
+      input,
+      stepIndex: i,
+    });
+
+    if (result?.ok === false) {
+      logs.push({ step: i, error: result.error });
+      throw new PipeError(
+        `Step ${i + 1} (${step.slug}) failed: ${result.error || "unknown error"}`
+      );
+    }
+
+    const value = result?.ok === true ? result.result : result;
+    outputs[i] = value;
+    onStep({ phase: "done", index: i, step, input, output: value, durationMs: result?.durationMs });
+  }
+
+  return { outputs, logs };
+}
+
+/** A pipeline failure with a message already written for a human. */
+export class PipeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PipeError";
+    this.expected = true;
+  }
+}
+
+// ─── Rendering ───────────────────────────────────────────────────────────────
+
+/** Render the wiring plan, the way the design called for. */
+export function renderPlan(plan) {
+  const lines = [];
+  const { steps, issues } = plan;
+
+  for (const step of steps) {
+    if (!step.manifest) {
+      lines.push(chalk.red(`  ✗ ${step.slug} — not found`));
+      continue;
+    }
+    lines.push(chalk.bold(`  ${step.slug}`));
+
+    for (const f of step.fields) {
+      const target = chalk.cyan(f.field);
+      const targetType = typeLabel(f.targetTypes);
+
+      if (f.expr.kind === "literal") {
+        lines.push(`    ${target} = ${chalk.dim(JSON.stringify(f.expr.literal))} ${chalk.gray(`(${targetType || "any"})`)}`);
+      } else if (f.expr.kind === "stdin") {
+        lines.push(`    ${target} = ${chalk.magenta("@in")} ${chalk.gray(`(${targetType || "any"})`)}`);
+      } else {
+        const chain = (f.expr.accessors || [])
+          .map((a) => (a.op === "transform" ? `|${a.name}` : a.path))
+          .join("");
+        const arrow = chalk.gray("←");
+        const src = chalk.dim(`${f.source?.slug ?? "?"}${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("✗")
+          : f.verdict === "lossy" ? chalk.yellow("~")
+          : chalk.green("✔");
+        lines.push(`    ${mark} ${target} ${arrow} ${src}  ${chalk.gray(`${got} → ${targetType || "any"}`)}`);
+      }
+    }
+    lines.push("");
+  }
+
+  const errors = issues.filter((i) => i.level === "error");
+  const warns = issues.filter((i) => i.level === "warn");
+  const lossy = issues.filter((i) => i.level === "warn" && /precision/.test(i.message));
+  const explicit = steps
+    .flatMap((s) => s.fields)
+    .filter((f) => f.expr?.accessors?.some((a) => a.op === "transform")).length;
+
+  if (issues.length) {
+    for (const issue of issues) {
+      const mark = issue.level === "error" ? chalk.red("  ✗") : chalk.yellow("  !");
+      lines.push(`${mark} step ${issue.step + 1}: ${issue.message}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    chalk.gray(
+      `  ${steps.length} step${steps.length === 1 ? "" : "s"} · ${errors.length} error${errors.length === 1 ? "" : "s"}` +
+      ` · ${lossy.length} lossy · ${explicit} explicit · runtime validation on`
+    )
+  );
+
+  return lines.join("\n");
+}
+
+/** One-line summary of a step's output for the run log. */
+export function describeOutput(value) {
+  if (value === MISSING || value === undefined) return chalk.gray("—");
+  if (value === null) return chalk.dim("null");
+  if (typeof value !== "object") return preview(value, 60);
+  const keys = Object.keys(value);
+  if (!keys.length) return chalk.dim("{}");
+  const parts = keys.slice(0, 4).map((k) => `${k}=${preview(value[k], 18)}`);
+  return parts.join(" ") + (keys.length > 4 ? chalk.gray(` +${keys.length - 4}`) : "");
+}