fix(debug): log structured HTTP error details instead of raw response (#1233)

* fix(debug): log structured HTTP error details instead of raw response

When an HTTP request fails, `debugApiResponse` now logs:

  * endpoint (description) — already was
  * status                 — already was
  * method, url, durationMs — already was
  * sanitized request headers (Authorization/api-keys redacted) — already was

And new fields that make support tickets actionable:

  * requestedAt — ISO-8601 timestamp of request start, for correlating
    with server-side logs.
  * cfRay       — Cloudflare trace id extracted as a top-level field
    from response headers (accepts `cf-ray` or `CF-Ray` casing).
  * responseHeaders — sanitized headers returned by the server.
  * responseBody   — string response body, truncated at 2_000 bytes
    so megabyte payloads don't balloon debug logs.

Wired into both the `queryApiSafeText` and `sendApiRequest` !ok
branches, which are the primary points where a non-thrown HTTP
error reaches a user. The success-path log includes the new
`requestedAt` timestamp too.

Added 5 new tests in `test/unit/utils/debug.test.mts` covering
requestedAt, cfRay (both casings), body passthrough, and body
truncation.

Existing debug-output shape preserved: callers that don't pass the
new fields (`responseHeaders`, `responseBody`, `requestedAt`) see
no change.

* fix(api): guard response.text() in error paths and label chars

Addresses Cursor bugbot feedback on PR #1233.

1. `result.text?.()` in the `!result.ok` branches of `queryApiSafeText`
   and `sendApiRequest` was unguarded. If `text()` threw, the exception
   propagated past the clean `{ ok: false, ... }` return and broke the
   error-handling contract. Wrap both call sites in a shared
   `tryReadResponseText` helper that swallows the failure and returns
   `undefined`.

2. The truncation suffix reported `body.length` as "bytes", but
   `String.prototype.length` / `String.prototype.slice` count UTF-16
   code units, not bytes. For non-ASCII response bodies the label was
   misleading. Rename to "chars" so the counter matches the actual
   measurement.

* chore(debug): trim redundant comments in API debug logging

* chore(debug): restore __proto__: null on API debug payload

* chore(debug): sort ApiRequestDebugInfo properties alphabetically

* refactor(debug): route API failure logs through the error namespace

* fix(ci): bump pnpm to 11.0.0-rc.3 to unblock CI

CI was failing with `pnpm: 1: This: not found` (exit 127) during the
install step because @pnpm/exe@11.0.0-rc.2 ships a broken shell shim —
its pnpm binary begins with "This..." which the shell tries to execute
as a command. Affects main too, not just this PR.

- Bump `packageManager` from `pnpm@11.0.0-rc.2` to `pnpm@11.0.0-rc.3`.
- Bump `engines.pnpm` to `>=11.0.0-rc.3` to match.
- Regenerate `pnpm-lock.yaml` with rc.3 — the new lockfile no longer
  pulls @pnpm/exe into packageManagerDependencies, which is why the
  footprint shrinks. @pnpm/exe stays in the allowBuilds allowlist in
  `pnpm-workspace.yaml` in case it's ever resolved transitively.

The socket-registry setup-and-install action (SHA a5923566c) already
installs pnpm rc.3, matching the upstream `_local-not-for-reuse-*`
workflows — so action pins do not need to change.

Author: jdalton

package.json

@@ -1,11 +1,11 @@
 {
   "name": "socket-cli-monorepo",
   "version": "0.0.0",
-  "packageManager": "pnpm@11.0.0-rc.2",
+  "packageManager": "pnpm@11.0.0-rc.3",
   "private": true,
   "engines": {
     "node": ">=25.9.0",
-    "pnpm": ">=11.0.0-rc.2"
+    "pnpm": ">=11.0.0-rc.3"
   },
   "scripts": {
     "// Build": "",

packages/cli/src/utils/debug.mts

@@ -29,12 +29,24 @@ import {
 } from '@socketsecurity/lib/debug'
 
 export type ApiRequestDebugInfo = {
+  durationMs?: number | undefined
+  headers?: Record<string, string> | undefined
   method?: string | undefined
+  // ISO-8601 timestamp of when the request was initiated. Useful when
+  // correlating failures with server-side logs.
+  requestedAt?: string | undefined
+  // Response body string; truncated by the helper to a safe length so
+  // logs don't balloon on megabyte payloads.
+  responseBody?: string | undefined
+  // Response headers from the failed request. The helper extracts the
+  // cf-ray trace id as a first-class field so support can look it up in
+  // the Cloudflare dashboard without eyeballing the whole header dump.
+  responseHeaders?: Record<string, string> | undefined
   url?: string | undefined
-  headers?: Record<string, string> | undefined
-  durationMs?: number | undefined
 }
 
+const RESPONSE_BODY_TRUNCATE_LENGTH = 2_000
+
 /**
  * Sanitize headers to remove sensitive information.
  * Redacts Authorization and API key headers.
@@ -77,15 +89,66 @@ export function debugApiRequest(
 }
 
 /**
- * Debug an API response with detailed request information.
- * Logs essential info without exposing sensitive data.
+ * Build the structured debug payload shared by the error + failure-status
+ * branches of `debugApiResponse`. Extracted so both paths log the same
+ * shape.
+ */
+function buildApiDebugDetails(
+  base: Record<string, unknown>,
+  requestInfo?: ApiRequestDebugInfo | undefined,
+): Record<string, unknown> {
+  // `__proto__: null` keeps the payload free of prototype-chain keys
+  // when callers iterate over the debug output.
+  const details: Record<string, unknown> = { __proto__: null, ...base } as Record<string, unknown>
+  if (!requestInfo) {
+    return details
+  }
+  if (requestInfo.requestedAt) {
+    details['requestedAt'] = requestInfo.requestedAt
+  }
+  if (requestInfo.method) {
+    details['method'] = requestInfo.method
+  }
+  if (requestInfo.url) {
+    details['url'] = requestInfo.url
+  }
+  if (requestInfo.durationMs !== undefined) {
+    details['durationMs'] = requestInfo.durationMs
+  }
+  if (requestInfo.headers) {
+    details['headers'] = sanitizeHeaders(requestInfo.headers)
+  }
+  if (requestInfo.responseHeaders) {
+    const cfRay =
+      requestInfo.responseHeaders['cf-ray'] ??
+      requestInfo.responseHeaders['CF-Ray']
+    if (cfRay) {
+      // First-class field so it's obvious when filing a support ticket
+      // that points at a Cloudflare trace.
+      details['cfRay'] = cfRay
+    }
+    details['responseHeaders'] = sanitizeHeaders(requestInfo.responseHeaders)
+  }
+  if (requestInfo.responseBody !== undefined) {
+    const body = requestInfo.responseBody
+    // `.length` / `.slice` operate on UTF-16 code units, not bytes, so
+    // the counter and truncation are both reported in "chars" to stay
+    // consistent with what we actually measured.
+    details['responseBody'] =
+      body.length > RESPONSE_BODY_TRUNCATE_LENGTH
+        ? `${body.slice(0, RESPONSE_BODY_TRUNCATE_LENGTH)}… (truncated, ${body.length} chars)`
+        : body
+  }
+  return details
+}
+
+/**
+ * Debug an API response. Failed requests (error or status >= 400) log
+ * under the `error` namespace; successful responses optionally log a
+ * one-liner under `notice`.
  *
- * For failed requests (status >= 400 or error), logs:
- * - HTTP method (GET, POST, etc.)
- * - Full URL
- * - Response status code
- * - Sanitized headers (Authorization redacted)
- * - Request duration in milliseconds
+ * Request and response headers are sanitized via `sanitizeHeaders` so
+ * Authorization and `*api-key*` values are redacted.
  */
 export function debugApiResponse(
   endpoint: string,
@@ -94,39 +157,21 @@ export function debugApiResponse(
   requestInfo?: ApiRequestDebugInfo | undefined,
 ): void {
   if (error) {
-    const errorDetails = {
-      __proto__: null,
-      endpoint,
-      error: error instanceof Error ? error.message : UNKNOWN_ERROR,
-      ...(requestInfo?.method ? { method: requestInfo.method } : {}),
-      ...(requestInfo?.url ? { url: requestInfo.url } : {}),
-      ...(requestInfo?.durationMs !== undefined
-        ? { durationMs: requestInfo.durationMs }
-        : {}),
-      ...(requestInfo?.headers
-        ? { headers: sanitizeHeaders(requestInfo.headers) }
-        : {}),
-    }
-    debugDir(errorDetails)
+    debugDirNs(
+      'error',
+      buildApiDebugDetails(
+        {
+          endpoint,
+          error: error instanceof Error ? error.message : UNKNOWN_ERROR,
+        },
+        requestInfo,
+      ),
+    )
   } else if (status && status >= 400) {
-    // For failed requests, log detailed information.
     if (requestInfo) {
-      const failureDetails = {
-        __proto__: null,
-        endpoint,
-        status,
-        ...(requestInfo.method ? { method: requestInfo.method } : {}),
-        ...(requestInfo.url ? { url: requestInfo.url } : {}),
-        ...(requestInfo.durationMs !== undefined
-          ? { durationMs: requestInfo.durationMs }
-          : {}),
-        ...(requestInfo.headers
-          ? { headers: sanitizeHeaders(requestInfo.headers) }
-          : {}),
-      }
-      debugDir(failureDetails)
+      debugDirNs('error', buildApiDebugDetails({ endpoint, status }, requestInfo))
     } else {
-      debug(`API ${endpoint}: HTTP ${status}`)
+      debugNs('error', `API ${endpoint}: HTTP ${status}`)
     }
     /* c8 ignore next 3 */
   } else if (isDebugNs('notice')) {

packages/cli/src/utils/socket/api.mts

@@ -82,6 +82,18 @@ export async function socketHttpRequest(
   return await httpRequest(url, options)
 }
 
+// Safe wrapper for `response.text()` in error-handling code paths.
+// `text()` can throw (e.g. already consumed, malformed body), which
+// would blow past the `ok: false` CResult return and break the
+// error-handling contract of callers like `queryApiSafeText`.
+function tryReadResponseText(result: HttpResponse): string | undefined {
+  try {
+    return result.text?.()
+  } catch {
+    return undefined
+  }
+}
+
 export type CommandRequirements = {
   permissions?: string[] | undefined
   quota?: number | undefined
@@ -428,6 +440,7 @@ export async function queryApiSafeText(
   const baseUrl = getDefaultApiBaseUrl()
   const fullUrl = `${baseUrl}${baseUrl?.endsWith('/') ? '' : '/'}${path}`
   const startTime = Date.now()
+  const requestedAt = new Date(startTime).toISOString()
 
   let result: any
   try {
@@ -443,6 +456,7 @@ export async function queryApiSafeText(
       method: 'GET',
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: { Authorization: '[REDACTED]' },
     })
   } catch (e) {
@@ -458,6 +472,7 @@ export async function queryApiSafeText(
       method: 'GET',
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: { Authorization: '[REDACTED]' },
     })
 
@@ -475,12 +490,17 @@ export async function queryApiSafeText(
   if (!result.ok) {
     const { status } = result
     const durationMs = Date.now() - startTime
-    // Log detailed error information.
+    // Include response headers (for cf-ray) and a truncated body so
+    // support tickets have everything needed to file against Cloudflare
+    // or backend teams.
     debugApiResponse(description || 'Query API', status, undefined, {
       method: 'GET',
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: { Authorization: '[REDACTED]' },
+      responseHeaders: result.headers,
+      responseBody: tryReadResponseText(result),
     })
     // Log required permissions for 403 errors when in a command context.
     if (commandPath && status === 403) {
@@ -587,6 +607,7 @@ export async function sendApiRequest<T>(
 
   const fullUrl = `${baseUrl}${baseUrl.endsWith('/') ? '' : '/'}${path}`
   const startTime = Date.now()
+  const requestedAt = new Date(startTime).toISOString()
 
   let result: any
   try {
@@ -614,6 +635,7 @@ export async function sendApiRequest<T>(
         method,
         url: fullUrl,
         durationMs,
+        requestedAt,
         headers: {
           Authorization: '[REDACTED]',
           'Content-Type': 'application/json',
@@ -633,6 +655,7 @@ export async function sendApiRequest<T>(
       method,
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: {
         Authorization: '[REDACTED]',
         'Content-Type': 'application/json',
@@ -653,15 +676,20 @@ export async function sendApiRequest<T>(
   if (!result.ok) {
     const { status } = result
     const durationMs = Date.now() - startTime
-    // Log detailed error information.
+    // Include response headers (for cf-ray) and a truncated body so
+    // support tickets have everything needed to file against Cloudflare
+    // or backend teams.
     debugApiResponse(description || 'Send API Request', status, undefined, {
       method,
       url: fullUrl,
       durationMs,
+      requestedAt,
       headers: {
         Authorization: '[REDACTED]',
         'Content-Type': 'application/json',
       },
+      responseHeaders: result.headers,
+      responseBody: tryReadResponseText(result),
     })
     // Log required permissions for 403 errors when in a command context.
     if (commandPath && status === 403) {