@hunt-labs/bytekit-cli 0.2.2 → 0.5.0

package/dist/output.js

@@ -1,6 +1,27 @@
 import { writeFileSync } from 'node:fs';
 /** 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.
  *
@@ -71,6 +92,47 @@ export function extractRawBody(response, requestedFormat) {
     }
     return value;
 }
+/**
+ * Exit code for `--raw`/`-o` against a 202 queued (async) scrape.
+ *
+ * Deliberately NOT 0 (a full raw-body success) and NOT 1 (a usage/API error): the job WAS accepted
+ * and billed, there is simply no content body to emit yet. A distinct code lets a caller branch on
+ * "queued" without parsing stderr.
+ */
+export const QUEUED_RAW_EXIT_CODE = 2;
+/** Is `result` a 202 queued scrape envelope carrying a job id? */
+function isQueuedEnvelope(result) {
+    if (typeof result !== 'object' || result === null)
+        return false;
+    const obj = result;
+    return obj.status === 'queued' && typeof obj.id === 'string' && obj.id.length > 0;
+}
+/**
+ * Handle `--raw`/`-o` on a 202 queued envelope.
+ *
+ * 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 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.exitCode = QUEUED_RAW_EXIT_CODE;
+}
 /**
  * Emit a raw body to the target.
  *
@@ -101,12 +163,25 @@ export function emitRaw(body, target) {
  */
 export function emitResult(result, mode, target, requestedFormat) {
     if (mode.kind === 'raw') {
+        // A 202 queued scrape has no format body to print — surface its `sc_` handle instead of
+        // throwing away the accepted (and billed) job. Scoped to raw mode only: json/human rendering
+        // 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);
@@ -115,6 +190,77 @@ 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 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 result (defensive — e.g. a
+ * bulk-fetch envelope routed here by mistake), so no path can silently emit nothing.
+ */
+export function emitFetchResult(result, jsonMode, target = {}) {
+    if (isFetchResult(result)) {
+        if (jsonMode) {
+            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(bytes);
+        return;
+    }
+    printResult(result, jsonMode);
+}
 /**
  * Print a result to stdout.
  *
@@ -122,7 +268,9 @@ export function emitResult(result, mode, target, requestedFormat) {
  */
 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) {
@@ -139,19 +287,52 @@ export function printResult(data, jsonMode) {
     }
     console.log(JSON.stringify(data, null, 2));
 }
+/** The SDK error classes whose `code` is a ByteKit diagnostic worth surfacing as a suffix. */
+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`
+ * write) — whose message already embeds the code, so suffixing them would render the redundant
+ * `Error: ENOENT: … (ENOENT)`. Only `ByteKitError` / `ByteKitConnectionError` codes qualify.
+ */
+function errorCode(err) {
+    if (!BYTEKIT_ERROR_NAMES.has(err.name))
+        return undefined;
+    const raw = err.code;
+    return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+}
 /**
  * Handle a CLI command error: print to stderr and exit 1.
+ *
+ * The message always begins `Error: ` (a prefix scripts grep on) followed by the error message and
+ * an optional parenthesised suffix built from the two diagnostic axes the ByteKit errors carry:
+ *
+ * - a `ByteKitError` from the transport carries both a numeric `status` and an API `code`
+ *   (`rate_limited`, `invalid_url`, …) → `Error: <message> (<code>, status: <n>)`;
+ * - a `ByteKitConnectionError` (client-side timeout / abort / socket failure) carries a `code`
+ *   (`timeout` | `aborted` | `connection`) but NO status → `Error: <message> (<code>)`;
+ * - a plain error with neither → `Error: <message>`.
+ *
+ * The `code` axis is read only off the two ByteKit error classes (see {@link errorCode}) — a plain
+ * 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>)`.
  */
 export function handleError(err) {
     if (err instanceof Error) {
-        const hasStatus = 'status' in err && typeof err.status === 'number';
+        const status = err.status;
+        const hasStatus = typeof status === 'number';
+        const code = errorCode(err);
+        let suffix = '';
         if (hasStatus) {
-            const apiErr = err;
-            console.error(`Error: ${apiErr.message} (status: ${apiErr.status})`);
+            suffix = code !== undefined ? ` (${code}, status: ${status})` : ` (status: ${status})`;
         }
-        else {
-            console.error(`Error: ${err.message}`);
+        else if (code !== undefined) {
+            suffix = ` (${code})`;
         }
+        console.error(`Error: ${err.message}${suffix}`);
     }
     else {
         console.error(`Error: ${String(err)}`);

package/package.json

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