@hunt-labs/bytekit-cli 0.3.0 → 0.6.0

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) {
@@ -206,7 +293,7 @@ const BYTEKIT_ERROR_NAMES = new Set(['ByteKitError', 'ByteKitConnectionError']);
  * A non-empty API/connection error `code`, or undefined when absent.
  *
  * Scoped by `err.name` to the ByteKit taxonomy: plenty of OTHER errors also carry a string
- * `.code` — Node fs/system errors (ENOENT from `parseUrlLines`'s readFileSync, EACCES on a `-o`
+ * `.code` — Node fs/system errors (ENOENT from `parseBulkLines`'s readFileSync, EACCES on a `-o`
  * write) — whose message already embeds the code, so suffixing them would render the redundant
  * `Error: ENOENT: … (ENOENT)`. Only `ByteKitError` / `ByteKitConnectionError` codes qualify.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.3.0"
+    "@hunt-labs/bytekit-sdk": "^0.5.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }

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);
-}