@hunt-labs/bytekit-cli 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -10,6 +10,63 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-08-31
+
+### Changed
+
+- Corrected the `detailValueText` doc comment in `src/output.ts`, which claimed the object arm of
+  the `details` renderer carried the SAME depth bound as the array arm through `detailJson`
+  (#3691). It carries the same **constant** (`DETAIL_MAX_DEPTH`), not the same **counter**:
+  `detailJson` takes no depth argument and starts a fresh budget from its own replacer chain. The
+  comment now records the two consequences — the arms agree level-for-level only on homogeneous
+  chains, and a mixed array/object chain can render up to `2 × DETAIL_MAX_DEPTH` levels — and why
+  threading `depth` into `detailJson` is not the fix: it would elide shapes that render today,
+  breaking the byte-identical inverse-case contract #3647 shipped under. **No consumer-visible
+  change** — this release touches one comment, and every `details` shape renders byte-identically
+  to 0.9.1.
+
+## [0.9.1] - 2026-08-27
+
+### Fixed
+
+- **A rejected request now names the field that was rejected.** When the API answers
+  `422 validation_error`, its envelope carries `details.fieldErrors` — the field the server
+  refused and what it will accept. The CLI dropped it twice over: its own transport parser never
+  read `error.details` off the envelope (the SDK has read it since `@hunt-labs/bytekit-sdk@0.6.0`),
+  and `handleError` rendered only the message, code and status. The result was
+  `Error: Invalid request body. (validation_error, status: 422)` and nothing else, in human and
+  `--json` modes alike, leaving `curl` as the only way to find out which field was wrong (#3538).
+
+  ```console
+  $ bytekit scrape create --url https://example.com --country zzzz
+  Error: Invalid request body. (validation_error, status: 422)
+  Details:
+    fieldErrors.country: String must contain exactly 2 character(s)
+  ```
+
+  The block is rendered on **stderr**, below the existing one-liner, and is **bounded** — at most
+  ten lines of at most 200 characters, with a `… and <n> more` line when there are further
+  entries — so an oversized or deeply nested `details` can never become a multi-KB dump in a
+  terminal. Nothing else changed: the `Error: ` prefix, the `(<code>, status: <n>)` suffix, exit
+  code `1` and the silence of stdout are all as before, and an error carrying no `details` (or a
+  `details` that is not a JSON object) prints exactly the single line it printed in `0.9.0`.
+  `--json` stdout stays byte-for-byte pipe-clean, because every byte of this goes to stderr.
+
+  The bound covers **depth** as well as size: the renderer descends at most eight array levels into
+  a `details` value and elides anything deeper as `…`. The line and width caps are applied after
+  that walk has finished, so on their own they could not stop a `details` payload nested thousands
+  of arrays deep — a body `JSON.parse` accepts, so a server can send one — from overflowing the
+  stack and printing a Node `RangeError` trace in place of the one-line error (#3633). Every
+  `details` shape the API sends renders byte-identically: nothing real is more than one array level
+  deep.
+
+  The same bound now covers the **object** arm of that walk. A `details` value that is a JSON object
+  was serialized with a bare `JSON.stringify`, which is itself natively recursive and overflowed the
+  stack on its own: flattening the key by one level bounds WHICH values are rendered, not how deep
+  each one is serialized, so a deeply object-nested payload still printed a `RangeError` trace
+  (#3647). Objects nested more than eight levels below the flattened key now elide as `…`, exactly
+  as over-deep arrays do. Everything shallower renders byte-identically, both live shapes included.
+
 ## [0.9.0] - 2026-08-20
 
 ### Removed

package/dist/client.js

@@ -231,15 +231,29 @@ function drainBestEffort(body, abort) {
  *     envelope shape, so a flat 502 rendered `internal_error` instead of `search_provider_error`).
  *
  * The explicit `!== null` guard on the envelope check matters — `typeof null` is `'object'`.
+ *
+ * The envelope's structured `details` is mirrored too (#3538). The SDK grew that read in #2685 and
+ * this copy did not follow, so a `422 validation_error`'s `fieldErrors` — the one fact naming WHICH
+ * field the server rejected — was parsed away before `handleError()` could render it: the same
+ * drift class as #2586, in the same function. Only the envelope arm reads it, and only when it is a
+ * JSON object: the flat vendor-masked arm has no envelope to read from and must never grow a
+ * phantom `details`, and `ByteKitErrorDetails` promises something indexable, so an array or a
+ * scalar is dropped rather than surfaced. `error-parser-parity.test.ts` compares this field against
+ * the real SDK's parser on a shared corpus.
  */
 async function toApiError(response) {
     let code = 'internal_error';
     let message = response.statusText;
+    let details;
     try {
         const json = (await response.json());
         if (typeof json.error === 'object' && json.error !== null) {
             code = json.error.code ?? code;
             message = json.error.message ?? message;
+            const raw = json.error.details;
+            if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+                details = raw;
+            }
         }
         else if (typeof json.error === 'string' && json.error.length > 0) {
             // The string IS the error code. `message` falls back to it only when the response carried
@@ -251,7 +265,7 @@ async function toApiError(response) {
     catch {
         // leave defaults
     }
-    return new ByteKitError(response.status, code, message);
+    return new ByteKitError(response.status, code, message, details);
 }
 /**
  * Perform the authenticated round-trip with a single bounded retry on 429, returning whatever the

package/dist/output.d.ts

@@ -204,6 +204,14 @@ export declare function printResult(data: unknown, jsonMode: boolean): void;
  * error carrying an unrelated string `.code` (a Node errno error) gets NO code suffix. When a
  * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
  * placeholder — never `(, status: <n>)`.
+ *
+ * When the error carries a structured `details` object — which a `422 validation_error` populates
+ * with zod's `fieldErrors`, naming WHICH field was rejected and what it accepts — a bounded
+ * `Details:` block follows on the SAME stderr write (#3538, see {@link detailBlock}). An error
+ * with no renderable `details` is byte-identical to before: one line, same text, same exit code.
+ *
+ * Everything goes to stderr, so `--json` stdout stays pipe-clean without this function needing to
+ * know which output mode is in effect.
  */
 export declare function handleError(err: unknown): void;
 export {};

package/dist/output.js

@@ -398,6 +398,161 @@ function errorCode(err) {
     const raw = err.code;
     return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
 }
+/**
+ * Human-mode bound on the rendered `details` block (#3538 E1).
+ *
+ * `details` is typed `unknown` on the wire — the API spec declares no schema for it — so nothing
+ * stops it from being arbitrarily large or deeply nested. Ten lines of at most 200 characters caps
+ * the block at ~2 KB: wider and longer than every validation envelope the API is observed to send
+ * (a handful of fields, one sentence each, so nothing real is ever truncated), and small enough
+ * that a pathological payload lands as a readable block rather than a multi-KB JSON dump.
+ */
+const DETAIL_MAX_LINES = 10;
+const DETAIL_MAX_LINE_CHARS = 200;
+/**
+ * Bound on the descent inside {@link detailValueText}: the array walk (#3633) and the object
+ * serialization in {@link detailJson} (#3647), which are the function's two recursive arms.
+ *
+ * The two caps above bound the block that is PRINTED; they are applied in {@link detailBlock},
+ * after the walk that builds each line has already finished, so neither of them bounds the walk
+ * itself. A `details` payload nested a few thousand arrays deep survives `JSON.parse` on the CLI's
+ * Node runtime, so a server can deliver one, and the descent overflowed the stack — the CLI dying
+ * with a raw `RangeError` trace instead of its documented one-line error.
+ *
+ * Eight levels is far past anything with meaning to render: the live shapes bottom out at ONE
+ * array level below the key {@link detailEntries} flattens, and a field→messages list has nowhere
+ * deeper to go. Below the bound the descent stops and emits the ellipsis, so an over-deep value is
+ * elided in the same visible way an over-long one is — never dropped, which would render a
+ * legitimate list as silence.
+ */
+const DETAIL_MAX_DEPTH = 8;
+/** A JSON object — the only `details` shape that has field→messages structure to render. */
+function isDetailRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * One detail value as a single line of text.
+ *
+ * Arrays are the zod `fieldErrors` shape — several messages about one field — and are joined with
+ * `; `. An object at this depth is already the SECOND level of nesting (see {@link detailEntries})
+ * and is emitted as compact JSON rather than flattened further: past that depth the key path is
+ * longer than the value it names.
+ *
+ * `depth` counts array levels already descended and is bounded by {@link DETAIL_MAX_DEPTH} (#3633);
+ * the object arm reuses the same CONSTANT through {@link detailJson} (#3647) but spends its OWN
+ * INDEPENDENT budget, counted from that call, and every remaining arm terminates on its own.
+ *
+ * Two budgets, not one, so: the arms agree level-for-level only on HOMOGENEOUS chains — an object
+ * sitting at array-depth 8 is not elided, while an array sitting at object-depth 8 is — and a mixed
+ * array/object chain can render up to `2 × DETAIL_MAX_DEPTH` nesting levels rather than
+ * `DETAIL_MAX_DEPTH`.
+ *
+ * Threading `depth` into {@link detailJson} is NOT the fix. It elides shapes that render today
+ * (measured across a 101-case corpus: 15 cases change instead of 10), which breaks the
+ * byte-identical inverse-case contract #3647 shipped under. Stack safety does not need it either:
+ * the array arm never resumes below an object, so the total descent is bounded at 8 + 8.
+ */
+function detailValueText(value, depth = 0) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        if (depth >= DETAIL_MAX_DEPTH)
+            return '…';
+        return value
+            .map((item) => detailValueText(item, depth + 1))
+            .filter((t) => t !== '')
+            .join('; ');
+    }
+    if (isDetailRecord(value))
+        return detailJson(value);
+    return String(value);
+}
+/**
+ * Compact JSON for an object detail value, bounded to {@link DETAIL_MAX_DEPTH} nesting levels
+ * (#3647).
+ *
+ * #3633 bounded the array descent above; this arm used a bare `JSON.stringify`, which is itself
+ * natively recursive and overflowed the stack on its own. The one-level flatten in
+ * {@link detailEntries} bounds the WALK, not the SERIALIZATION: `{a: {b: X}}` yields the single
+ * entry `a.b` whose value `X` was handed straight to `JSON.stringify`, which then recursed to the
+ * bottom of `X` — the same raw `RangeError` in place of the documented one-line error, from the
+ * arm next door.
+ *
+ * The bound is the same eight levels and is applied by a replacer, so everything shallower than it
+ * serializes through the untouched native path and renders byte-identically: escaping, key order,
+ * dropped `undefined`s, `toJSON`. `ancestors` is the chain of holders the replacer is currently
+ * inside — `this` is the holder of each visited key, so popping back to it yields the depth — and
+ * only a value that would RECURSE is elided, which is what keeps a leaf sitting at the bound
+ * rendering exactly as the array arm's leaf at the same depth does.
+ */
+function detailJson(value) {
+    const ancestors = [];
+    return JSON.stringify(value, function (_key, entry) {
+        while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this)
+            ancestors.pop();
+        if (ancestors.length >= DETAIL_MAX_DEPTH && typeof entry === 'object' && entry !== null) {
+            return '…';
+        }
+        ancestors.push(entry);
+        return entry;
+    });
+}
+/**
+ * The `key → value` pairs to render, flattened by exactly ONE level.
+ *
+ * Two `details` shapes are live (both pinned verbatim from staging by the SDK's parser suite):
+ * a 422 `validation_error` carries zod's `flatten()` output — `{formErrors, fieldErrors}` — where
+ * the field name lives one level down under `fieldErrors`; a 400 `invalid_url` carries a flat
+ * record (`{url, field, reason}`). One level of flattening renders both with a single rule and no
+ * per-shape special case: `fieldErrors.formats: …` and `url: …` respectively.
+ */
+function detailEntries(details) {
+    const entries = [];
+    for (const [key, value] of Object.entries(details)) {
+        if (isDetailRecord(value)) {
+            for (const [inner, innerValue] of Object.entries(value)) {
+                entries.push([`${key}.${inner}`, innerValue]);
+            }
+        }
+        else {
+            entries.push([key, value]);
+        }
+    }
+    return entries;
+}
+/**
+ * The stderr block that renders a `ByteKitError.details` (#3538), or `''` when there is nothing to
+ * render.
+ *
+ * A `422 validation_error` envelope carries `details.fieldErrors` naming the offending field and
+ * its allowed values; the CLI printed only `message`/`code`/`status`, so the one fact the caller
+ * needed was dropped and reproducing the call with curl was the only recourse.
+ *
+ * Returns `''` — leaving the rendered line byte-identical to before — whenever `details` is
+ * absent, is not a JSON object (the untyped spec field permits a string, an array, `null`), or
+ * carries no non-empty value. `formErrors: []` on a passing form is the ordinary case of the last
+ * one: an empty bag is not a reason.
+ */
+function detailBlock(details) {
+    if (!isDetailRecord(details))
+        return '';
+    const lines = detailEntries(details).flatMap(([key, value]) => {
+        const text = detailValueText(value);
+        return text === '' ? [] : [`  ${key}: ${text}`];
+    });
+    if (lines.length === 0)
+        return '';
+    const shown = lines.length > DETAIL_MAX_LINES
+        ? [
+            ...lines.slice(0, DETAIL_MAX_LINES - 1),
+            `  … and ${lines.length - (DETAIL_MAX_LINES - 1)} more`,
+        ]
+        : lines;
+    return [
+        'Details:',
+        ...shown.map((line) => line.length > DETAIL_MAX_LINE_CHARS ? `${line.slice(0, DETAIL_MAX_LINE_CHARS - 1)}…` : line),
+    ].join('\n');
+}
 /**
  * Handle a CLI command error: print to stderr and signal exit 1.
  *
@@ -427,6 +582,14 @@ function errorCode(err) {
  * error carrying an unrelated string `.code` (a Node errno error) gets NO code suffix. When a
  * status is present but no code (a hand-built error), the suffix is `(status: <n>)` with no empty
  * placeholder — never `(, status: <n>)`.
+ *
+ * When the error carries a structured `details` object — which a `422 validation_error` populates
+ * with zod's `fieldErrors`, naming WHICH field was rejected and what it accepts — a bounded
+ * `Details:` block follows on the SAME stderr write (#3538, see {@link detailBlock}). An error
+ * with no renderable `details` is byte-identical to before: one line, same text, same exit code.
+ *
+ * Everything goes to stderr, so `--json` stdout stays pipe-clean without this function needing to
+ * know which output mode is in effect.
  */
 export function handleError(err) {
     if (err instanceof Error) {
@@ -440,7 +603,8 @@ export function handleError(err) {
         else if (code !== undefined) {
             suffix = ` (${code})`;
         }
-        console.error(`Error: ${err.message}${suffix}`);
+        const details = detailBlock(err.details);
+        console.error(`Error: ${err.message}${suffix}${details === '' ? '' : `\n${details}`}`);
     }
     else {
         console.error(`Error: ${String(err)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.9.0"
+    "@hunt-labs/bytekit-sdk": "^0.9.1"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",