@hunt-labs/bytekit-cli 0.3.0 → 0.5.0

package/dist/lib/parse-flags.d.ts

@@ -14,3 +14,33 @@ export declare function parseIntFlag(flag: string, value: string): number;
 export declare function parseEnum<T extends string>(flag: string, allowed: readonly T[], value: string): T;
 /** Split a comma-separated flag value into a trimmed, non-empty string array. */
 export declare function parseCsv(value: string): string[];
+/**
+ * Parse a finite decimal flag value (#2545). Unlike {@link parseIntFlag}, the `/^\d+(\.\d+)?$/`
+ * test accepts a fractional value such as `2.5` — required for spec `type: number` fields like
+ * `monitors change_threshold` (default 5, range 0–100) that `parseIntFlag`'s `/^\d+$/` would reject
+ * at parse time. Rejects `abc`, ``, `-5`, `1.` and `1e2` with the flag named in the message.
+ */
+export declare function parseNumberFlag(flag: string, value: string): number;
+/**
+ * Parse a `cache_ttl` flag value (#2545). Mirrors the gateway validator's own format grammar
+ * (`^(0|\d+[hd])$`, `packages/gateway/src/validators/shared.ts`) locally so an off-grammar value
+ * (`30m`, `soon`) is rejected at parse time with an actionable message instead of a server 422.
+ * The string is returned verbatim — the validator accepts the string `'0'`, and the range cap
+ * (7d/168h for scrape+fetch) stays a server-side concern.
+ */
+export declare function parseCacheTtl(flag: string, value: string): string;
+/**
+ * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
+ * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
+ * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
+ * does not match `expect`, with a copy-pasteable example in the message (E5).
+ */
+export declare function parseJsonFlag(flag: string, value: string, expect: 'object' | 'array'): unknown;
+/**
+ * Commander collector for a repeatable, CSV-aware `--format` flag (#2545). Each occurrence is
+ * CSV-split and appended to the accumulator, so `--format raw_html --format markdown` and
+ * `--format raw_html,markdown` both yield `['raw_html','markdown']`. Commander seeds `prev` with
+ * the option default (or the previous return) on each occurrence.
+ */
+export declare function collectFormats(value: string, prev: string[] | undefined): string[];

package/dist/lib/parse-flags.js

@@ -30,3 +30,61 @@ export function parseCsv(value) {
         .map((s) => s.trim())
         .filter((s) => s.length > 0);
 }
+/**
+ * Parse a finite decimal flag value (#2545). Unlike {@link parseIntFlag}, the `/^\d+(\.\d+)?$/`
+ * test accepts a fractional value such as `2.5` — required for spec `type: number` fields like
+ * `monitors change_threshold` (default 5, range 0–100) that `parseIntFlag`'s `/^\d+$/` would reject
+ * at parse time. Rejects `abc`, ``, `-5`, `1.` and `1e2` with the flag named in the message.
+ */
+export function parseNumberFlag(flag, value) {
+    if (!/^\d+(\.\d+)?$/.test(value)) {
+        throw new InvalidArgumentError(`${flag} must be a number.`);
+    }
+    return Number(value);
+}
+/**
+ * Parse a `cache_ttl` flag value (#2545). Mirrors the gateway validator's own format grammar
+ * (`^(0|\d+[hd])$`, `packages/gateway/src/validators/shared.ts`) locally so an off-grammar value
+ * (`30m`, `soon`) is rejected at parse time with an actionable message instead of a server 422.
+ * The string is returned verbatim — the validator accepts the string `'0'`, and the range cap
+ * (7d/168h for scrape+fetch) stays a server-side concern.
+ */
+export function parseCacheTtl(flag, value) {
+    if (!/^(0|\d+[hd])$/.test(value)) {
+        throw new InvalidArgumentError(`${flag} must be 0, Nh (hours), or Nd (days) — e.g. 48h, 2d, 0.`);
+    }
+    return value;
+}
+/**
+ * Parse a JSON-object- or JSON-array-valued flag (#2545). The ONLY `JSON.parse` call site for CLI
+ * flag values — every JSON-shaped flag (`--cookies`, `--headers`, `--custom`,
+ * `--webhook-headers`, `--options`, `--scrape-options`) routes through here, so command modules
+ * carry no raw `JSON.parse` (grep-gated). Rejects malformed JSON AND a value whose top-level shape
+ * does not match `expect`, with a copy-pasteable example in the message (E5).
+ */
+export function parseJsonFlag(flag, value, expect) {
+    const example = expect === 'array' ? `[{"name":"a","value":"b"}]` : `{"X-Header":"value"}`;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new InvalidArgumentError(`${flag} must be valid JSON (a ${expect}), e.g. '${example}'.`);
+    }
+    const matches = expect === 'array'
+        ? Array.isArray(parsed)
+        : typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
+    if (!matches) {
+        throw new InvalidArgumentError(`${flag} must be a JSON ${expect}, e.g. '${example}'.`);
+    }
+    return parsed;
+}
+/**
+ * Commander collector for a repeatable, CSV-aware `--format` flag (#2545). Each occurrence is
+ * CSV-split and appended to the accumulator, so `--format raw_html --format markdown` and
+ * `--format raw_html,markdown` both yield `['raw_html','markdown']`. Commander seeds `prev` with
+ * the option default (or the previous return) on each occurrence.
+ */
+export function collectFormats(value, prev) {
+    return [...(prev ?? []), ...parseCsv(value)];
+}

package/dist/output.d.ts

@@ -22,6 +22,24 @@ export interface OutputFlags {
     raw?: boolean | undefined;
     output?: string | undefined;
 }
+/**
+ * Serialize a value as the CLI's `--json` payload text. The single serializer EVERY `--json`
+ * branch in this module goes through, so no branch can regress to a raw `JSON.stringify`.
+ *
+ * `JSON.stringify` returns the VALUE `undefined` — not a string — for `undefined`, functions and
+ * symbols. Handed to `console.log` that prints the literal text `undefined`, which is NOT valid
+ * JSON and breaks every `| jq` pipeline; handed to `writeFileSync` it throws
+ * `ERR_INVALID_ARG_TYPE`. A `204 No Content` response resolves to `undefined` in the SDK
+ * (`monitors.delete` is typed `Promise<void>`), so this is the ORDINARY shape of
+ * `bytekit monitors delete <id> --json`, not an exotic edge case (#2544).
+ *
+ * The representation is JSON `null` — the canonical JSON spelling of "no content". Deliberately
+ * NOT a synthesized envelope such as `{"status":"deleted"}`: that is a shape the API never
+ * returned, and it would have to be re-invented (and kept consistent) per command. `null` is
+ * uniform across every 204-returning path, and `… --json | jq .` prints `null` and exits 0.
+ * The contract is documented in README (`Exit codes and output contracts`) and CHANGELOG.
+ */
+export declare function toJsonText(data: unknown): string;
 /**
  * Resolve the output mode from the flags, and enforce the `--json` / `--raw` exclusion.
  *
@@ -75,10 +93,21 @@ interface QueuedEnvelope {
  * The user asked for a content body that does not exist yet — but the job was accepted, so losing
  * the handle (the old behaviour: throw `--raw: response contains no formats`, exit 1) is the real
  * defect. Instead: emit the `sc_` id to STDOUT so `$(bytekit scrape create … --raw)` still captures
- * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and exit
- * with {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and signal
+ * {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ *
+ * The exit code is a SOFT `process.exitCode`, never a hard `process.exit` (#2544). Node documents
+ * `process.stdout` as ASYNCHRONOUS when it points at a pipe: a write that cannot be handed to the
+ * kernel in one go is queued in userspace and drained on a later event-loop turn, and
+ * `process.exit()` runs before any of those turns and DISCARDS the queue. That is exactly the
+ * `sc=$(bytekit scrape create … --async --raw)` case this branch exists to serve — the id would be
+ * truncated away whenever stdout is backlogged. Setting `process.exitCode` instead lets the process
+ * end naturally once stdout has drained, with the same observable exit code.
+ *
+ * Returns `void` (not `never`): callers MUST `return` after invoking it, since execution now
+ * continues past this function.
  */
-export declare function emitQueuedRaw(env: QueuedEnvelope): never;
+export declare function emitQueuedRaw(env: QueuedEnvelope): void;
 /**
  * Emit a raw body to the target.
  *
@@ -101,18 +130,27 @@ export declare function emitRaw(body: string, target: OutputTarget): void;
  * `--json | jq` pipelines stay byte-identical.
  */
 export declare function emitResult(result: unknown, mode: OutputMode, target: OutputTarget, requestedFormat?: string): void;
+/**
+ * Collect the `X-Fetch-*` response headers of a {@link FetchResult} into a Title-Cased object —
+ * the documented `--json` payload for a fetch command.
+ */
+export declare function collectFetchMetadata(headers: Headers): Record<string, string>;
 /**
  * Render a `/v1/fetch` content result.
  *
- * The transport hands back a {@link FetchBodyResult} whose body IS the fetched content and whose
- * metadata are the `X-Fetch-*` headers. Default: write the raw body bytes to stdout verbatim
- * (`process.stdout.write`, never `console.log` — no coercion, no appended newline, binary-safe).
- * With `--json`: print the `X-Fetch-*` metadata as JSON instead of the body.
+ * The SDK's fetch resource resolves a {@link FetchResult} whose `bytes` ARE the fetched content and
+ * whose `headers` carry the `X-Fetch-*` metadata.
+ *
+ * - default — write the raw body BYTES verbatim (`process.stdout.write`, never `console.log`: no
+ *   coercion, no appended newline, binary-safe). `bytes` is used rather than the `body` string
+ *   because the string is a lossy UTF-8 decode for true binary passthrough (images, PDFs).
+ * - `--json` — print the `X-Fetch-*` metadata object instead of the body.
+ * - `target.file` — write the same bytes to that path instead of stdout, byte-for-byte.
  *
- * Falls back to {@link printResult} for any result that is not a fetch body (defensive — e.g. a
+ * Falls back to {@link printResult} for any result that is not a fetch result (defensive — e.g. a
  * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
  */
-export declare function emitFetchResult(result: unknown, jsonMode: boolean): void;
+export declare function emitFetchResult(result: unknown, jsonMode: boolean, target?: OutputTarget): void;
 /**
  * Print a result to stdout.
  *

package/dist/output.js

@@ -1,7 +1,27 @@
 import { writeFileSync } from 'node:fs';
-import { isFetchBodyResult } from './lib/fetch-body.js';
 /** Text formats whose bodies are strings and can therefore be emitted raw. */
 const TEXT_FORMATS = 'markdown, html, raw_html';
+/**
+ * Serialize a value as the CLI's `--json` payload text. The single serializer EVERY `--json`
+ * branch in this module goes through, so no branch can regress to a raw `JSON.stringify`.
+ *
+ * `JSON.stringify` returns the VALUE `undefined` — not a string — for `undefined`, functions and
+ * symbols. Handed to `console.log` that prints the literal text `undefined`, which is NOT valid
+ * JSON and breaks every `| jq` pipeline; handed to `writeFileSync` it throws
+ * `ERR_INVALID_ARG_TYPE`. A `204 No Content` response resolves to `undefined` in the SDK
+ * (`monitors.delete` is typed `Promise<void>`), so this is the ORDINARY shape of
+ * `bytekit monitors delete <id> --json`, not an exotic edge case (#2544).
+ *
+ * The representation is JSON `null` — the canonical JSON spelling of "no content". Deliberately
+ * NOT a synthesized envelope such as `{"status":"deleted"}`: that is a shape the API never
+ * returned, and it would have to be re-invented (and kept consistent) per command. `null` is
+ * uniform across every 204-returning path, and `… --json | jq .` prints `null` and exits 0.
+ * The contract is documented in README (`Exit codes and output contracts`) and CHANGELOG.
+ */
+export function toJsonText(data) {
+    const text = JSON.stringify(data, null, 2);
+    return text === undefined ? 'null' : text;
+}
 /**
  * Resolve the output mode from the flags, and enforce the `--json` / `--raw` exclusion.
  *
@@ -93,14 +113,25 @@ function isQueuedEnvelope(result) {
  * The user asked for a content body that does not exist yet — but the job was accepted, so losing
  * the handle (the old behaviour: throw `--raw: response contains no formats`, exit 1) is the real
  * defect. Instead: emit the `sc_` id to STDOUT so `$(bytekit scrape create … --raw)` still captures
- * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and exit
- * with {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ * a usable handle, print a human note to STDERR explaining it is queued and how to poll, and signal
+ * {@link QUEUED_RAW_EXIT_CODE} — distinguishable from both success and error.
+ *
+ * The exit code is a SOFT `process.exitCode`, never a hard `process.exit` (#2544). Node documents
+ * `process.stdout` as ASYNCHRONOUS when it points at a pipe: a write that cannot be handed to the
+ * kernel in one go is queued in userspace and drained on a later event-loop turn, and
+ * `process.exit()` runs before any of those turns and DISCARDS the queue. That is exactly the
+ * `sc=$(bytekit scrape create … --async --raw)` case this branch exists to serve — the id would be
+ * truncated away whenever stdout is backlogged. Setting `process.exitCode` instead lets the process
+ * end naturally once stdout has drained, with the same observable exit code.
+ *
+ * Returns `void` (not `never`): callers MUST `return` after invoking it, since execution now
+ * continues past this function.
  */
 export function emitQueuedRaw(env) {
     console.error(`Note: scrape ${env.id} was queued (async) — no content body is available yet. ` +
         `Poll it with: bytekit scrape get ${env.id}`);
     process.stdout.write(`${env.id}\n`);
-    process.exit(QUEUED_RAW_EXIT_CODE);
+    process.exitCode = QUEUED_RAW_EXIT_CODE;
 }
 /**
  * Emit a raw body to the target.
@@ -137,15 +168,20 @@ export function emitResult(result, mode, target, requestedFormat) {
         // of a queued envelope stays unchanged (falls through to printResult below). A `-o <file>`
         // target is deliberately ignored here (id always on STDOUT, never written to the file): there
         // is no content body yet, and a file holding a bare `sc_` id would masquerade as content.
+        // `emitQueuedRaw` signals via a soft `process.exitCode` and RETURNS (#2544), so this branch
+        // must stop explicitly. Falling through would run `extractRawBody` on a formats-less queued
+        // envelope, throwing `--raw: response contains no formats` and clobbering the queued signal
+        // with the generic exit 1.
         if (isQueuedEnvelope(result)) {
             emitQueuedRaw(result);
+            return;
         }
         emitRaw(extractRawBody(result, requestedFormat), target);
         return;
     }
     if (mode.kind === 'json') {
         if (target.file !== undefined) {
-            writeFileSync(target.file, JSON.stringify(result, null, 2));
+            writeFileSync(target.file, toJsonText(result));
             return;
         }
         printResult(result, true);
@@ -154,24 +190,73 @@ export function emitResult(result, mode, target, requestedFormat) {
     // human — unreachable with a file destination (resolveOutputMode never yields it alongside one).
     printResult(result, false);
 }
+/** Title-Case an HTTP header name segment-by-segment: `x-fetch-status` → `X-Fetch-Status`. */
+function titleCaseHeader(name) {
+    return name
+        .split('-')
+        .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1).toLowerCase())
+        .join('-');
+}
+/**
+ * Collect the `X-Fetch-*` response headers of a {@link FetchResult} into a Title-Cased object —
+ * the documented `--json` payload for a fetch command.
+ */
+export function collectFetchMetadata(headers) {
+    const meta = {};
+    headers.forEach((value, key) => {
+        if (key.toLowerCase().startsWith('x-fetch-')) {
+            meta[titleCaseHeader(key)] = value;
+        }
+    });
+    return meta;
+}
+/**
+ * Narrow an SDK response to the `FetchResult` the fetch resource resolves.
+ *
+ * Structural, not a branded tag: the shape is the SDK's PUBLIC contract (`bytes` + `headers`), so
+ * the guard stays true across SDK transport refactors. The CLI previously narrowed on a CLI-owned
+ * `__bytekitFetchBody` brand its own transport stamped — which stopped matching the moment the SDK
+ * moved `/v1/fetch` onto `requestRaw` (#2535), silently demoting every fetch to the key/value
+ * printer. `fetch-contract.test.ts` pins this guard against the real SDK.
+ */
+function isFetchResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return v.bytes instanceof Uint8Array && v.headers instanceof Headers;
+}
 /**
  * Render a `/v1/fetch` content result.
  *
- * The transport hands back a {@link FetchBodyResult} whose body IS the fetched content and whose
- * metadata are the `X-Fetch-*` headers. Default: write the raw body bytes to stdout verbatim
- * (`process.stdout.write`, never `console.log` — no coercion, no appended newline, binary-safe).
- * With `--json`: print the `X-Fetch-*` metadata as JSON instead of the body.
+ * The SDK's fetch resource resolves a {@link FetchResult} whose `bytes` ARE the fetched content and
+ * whose `headers` carry the `X-Fetch-*` metadata.
+ *
+ * - default — write the raw body BYTES verbatim (`process.stdout.write`, never `console.log`: no
+ *   coercion, no appended newline, binary-safe). `bytes` is used rather than the `body` string
+ *   because the string is a lossy UTF-8 decode for true binary passthrough (images, PDFs).
+ * - `--json` — print the `X-Fetch-*` metadata object instead of the body.
+ * - `target.file` — write the same bytes to that path instead of stdout, byte-for-byte.
  *
- * Falls back to {@link printResult} for any result that is not a fetch body (defensive — e.g. a
+ * Falls back to {@link printResult} for any result that is not a fetch result (defensive — e.g. a
  * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
  */
-export function emitFetchResult(result, jsonMode) {
-    if (isFetchBodyResult(result)) {
+export function emitFetchResult(result, jsonMode, target = {}) {
+    if (isFetchResult(result)) {
         if (jsonMode) {
-            console.log(JSON.stringify(result.metadata, null, 2));
+            const metadata = toJsonText(collectFetchMetadata(result.headers));
+            if (target.file !== undefined) {
+                writeFileSync(target.file, metadata);
+                return;
+            }
+            console.log(metadata);
+            return;
+        }
+        const bytes = Buffer.from(result.bytes);
+        if (target.file !== undefined) {
+            writeFileSync(target.file, bytes);
             return;
         }
-        process.stdout.write(result.body);
+        process.stdout.write(bytes);
         return;
     }
     printResult(result, jsonMode);
@@ -183,7 +268,9 @@ export function emitFetchResult(result, jsonMode) {
  */
 export function printResult(data, jsonMode) {
     if (jsonMode) {
-        console.log(JSON.stringify(data, null, 2));
+        // Always via toJsonText: a 204 hands us `undefined`, whose raw JSON.stringify is the VALUE
+        // undefined and would print the literal, unparseable text `undefined` (#2544).
+        console.log(toJsonText(data));
         return;
     }
     if (data === null || data === undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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.3.0"
+    "@hunt-labs/bytekit-sdk": "^0.4.0"
   },
   "scripts": {
     "build": "tsc",

package/dist/lib/fetch-body.d.ts

@@ -1,18 +0,0 @@
-/**
- * A raw (non-JSON) response body from a `/v1/fetch` content request, plus its `X-Fetch-*` metadata.
- *
- * The `/v1/fetch` content endpoints (POST and GET) return the fetched bytes AS the body — HTML,
- * markdown, or arbitrary binary — with all metadata in `X-Fetch-*` response headers. Every OTHER
- * endpoint (including `/v1/fetch/bulk`) returns a JSON envelope. The CLI transport tags a content
- * result with this shape so the `fetch` command can print the body verbatim (default) or the
- * metadata as JSON (`--json`), instead of JSON-parsing a body that was never JSON to begin with.
- */
-export interface FetchBodyResult {
-    readonly __bytekitFetchBody: true;
-    /** The raw response body bytes, uncorrupted — safe for binary content (no string coercion). */
-    readonly body: Buffer;
-    /** The `X-Fetch-*` response headers, Title-Cased (`x-fetch-status` → `X-Fetch-Status`). */
-    readonly metadata: Record<string, string>;
-}
-/** Narrow an arbitrary transport result to a {@link FetchBodyResult}. */
-export declare function isFetchBodyResult(value: unknown): value is FetchBodyResult;

package/dist/lib/fetch-body.js

@@ -1,6 +0,0 @@
-/** Narrow an arbitrary transport result to a {@link FetchBodyResult}. */
-export function isFetchBodyResult(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.__bytekitFetchBody === true);
-}