refactor: api command uses return-based output, remove buildDryRunRequest

Both code paths now return { data } through the standard output system:
- Dry-run: returns { data: { method, url, headers, body } } preview
- Normal: returns { data: response.body } after side-effect writes
  (verbose/include headers, error exit code)

Key changes:
- output: 'json' → { json: true } (JSON-only config, no human formatter)
- Make OutputConfig.human optional — when absent, renderCommandOutput
  always serializes as JSON regardless of --json flag
- Remove buildDryRunRequest — inline request preview construction using
  resolveRequestUrl + new resolveEffectiveHeaders helper
- Remove handleResponse — its behaviors are inlined in func:
  verbose/include headers as pre-return side effects, silent mode
  returns void, error uses process.exitCode (not process.exit) so
  the output wrapper can render before the process exits
- Remove DryRunRequest type, writeJson import

Tests: replace handleResponse tests (8) and buildDryRunRequest tests
(4+5 property) with resolveEffectiveHeaders tests (6+4 property).
288 tests pass across 3 files.

Author: BYK

src/commands/api.ts

@@ -9,7 +9,6 @@ import type { SentryContext } from "../context.js";
 import { buildSearchParams, rawApiRequest } from "../lib/api-client.js";
 import { buildCommand } from "../lib/command.js";
 import { ValidationError } from "../lib/errors.js";
-import { writeJson } from "../lib/formatters/json.js";
 import { validateEndpoint } from "../lib/input-validation.js";
 import { getDefaultSdkConfig } from "../lib/sentry-client.js";
 import type { Writer } from "../types/index.js";
@@ -27,9 +26,9 @@ type ApiFlags = {
   readonly silent: boolean;
   readonly verbose: boolean;
   readonly "dry-run": boolean;
-  /** Injected by buildCommand via output: "json" */
+  /** Injected by buildCommand via output: { json: true } */
   readonly json: boolean;
-  /** Injected by buildCommand via output: "json" */
+  /** Injected by buildCommand via output: { json: true } */
   readonly fields?: string[];
 };
 
@@ -938,95 +937,27 @@ export function resolveRequestUrl(
 }
 
 /**
- * Dry-run request details — everything that would be sent without actually sending.
- */
-export type DryRunRequest = {
-  method: string;
-  url: string;
-  headers: Record<string, string>;
-  body: unknown;
-};
-
-/**
- * Build a DryRunRequest from the resolved request components.
+ * Resolve effective request headers, mirroring rawApiRequest logic.
  *
- * Mirrors the URL and header logic from rawApiRequest so the
- * preview matches what the real request would look like.
+ * Auto-adds Content-Type: application/json for non-string object bodies
+ * when no Content-Type was explicitly provided.
  *
  * @internal Exported for testing
  */
-export function buildDryRunRequest(
-  method: string,
-  endpoint: string,
-  options: {
-    params?: Record<string, string | string[]>;
-    headers?: Record<string, string>;
-    body?: unknown;
-  }
-): DryRunRequest {
-  const headers = { ...(options.headers ?? {}) };
-
-  // Mirror rawApiRequest: auto-add Content-Type for object bodies
-  // when no Content-Type was explicitly provided
+export function resolveEffectiveHeaders(
+  customHeaders: Record<string, string> | undefined,
+  body: unknown
+): Record<string, string> {
+  const headers = { ...(customHeaders ?? {}) };
   if (
-    options.body !== undefined &&
-    options.body !== null &&
-    typeof options.body !== "string" &&
+    body !== undefined &&
+    body !== null &&
+    typeof body !== "string" &&
     !Object.keys(headers).some((k) => k.toLowerCase() === "content-type")
   ) {
     headers["Content-Type"] = "application/json";
   }
-
-  return {
-    method,
-    url: resolveRequestUrl(endpoint, options.params),
-    headers,
-    body: options.body ?? null,
-  };
-}
-
-/**
- * Handle response output based on flags
- * @internal Exported for testing
- */
-export function handleResponse(
-  stdout: Writer,
-  response: { status: number; headers: Headers; body: unknown },
-  flags: {
-    silent: boolean;
-    verbose: boolean;
-    include: boolean;
-    fields?: string[];
-  }
-): void {
-  const isError = response.status >= 400;
-
-  // Silent mode - only set exit code
-  if (flags.silent) {
-    if (isError) {
-      process.exit(1);
-    }
-    return;
-  }
-
-  // Output headers (verbose or include mode)
-  if (flags.verbose) {
-    writeVerboseResponse(stdout, response.status, response.headers);
-  } else if (flags.include) {
-    writeResponseHeaders(stdout, response.status, response.headers);
-  }
-
-  // Output body — apply --fields filtering when requested
-  if (flags.fields && flags.fields.length > 0) {
-    writeJson(stdout, response.body, flags.fields);
-  } else {
-    writeResponseBody(stdout, response.body);
-  }
-
-  // Exit with error code for error responses
-  if (isError) {
-    process.exit(1);
-  }
+  return headers;
 }
 
 /**
@@ -1152,7 +1083,7 @@ export async function resolveBody(
 // Command Definition
 
 export const apiCommand = buildCommand({
-  output: "json",
+  output: { json: true },
   docs: {
     brief: "Make an authenticated API request",
     fullDescription:
@@ -1275,18 +1206,19 @@ export const apiCommand = buildCommand({
         ? parseHeaders(flags.header)
         : undefined;
 
-    // Dry-run mode: show the resolved request without sending it
+    // Dry-run mode: preview the request that would be sent
     if (flags["dry-run"]) {
-      const request = buildDryRunRequest(flags.method, normalizedEndpoint, {
-        params,
-        headers,
-        body,
-      });
-      writeJson(stdout, request, flags.fields);
-      return;
+      return {
+        data: {
+          method: flags.method,
+          url: resolveRequestUrl(normalizedEndpoint, params),
+          headers: resolveEffectiveHeaders(headers, body),
+          body: body ?? null,
+        },
+      };
     }
 
-    // Verbose mode: show request details (unless silent)
+    // Verbose mode: show request details before the response
     if (flags.verbose && !flags.silent) {
       writeVerboseRequest(stdout, flags.method, normalizedEndpoint, headers);
     }
@@ -1298,6 +1230,28 @@ export const apiCommand = buildCommand({
       headers,
     });
 
-    handleResponse(stdout, response, flags);
+    const isError = response.status >= 400;
+
+    // Silent mode — only set exit code, no output
+    if (flags.silent) {
+      if (isError) {
+        process.exit(1);
+      }
+      return;
+    }
+
+    // Output response headers when requested
+    if (flags.verbose) {
+      writeVerboseResponse(stdout, response.status, response.headers);
+    } else if (flags.include) {
+      writeResponseHeaders(stdout, response.status, response.headers);
+    }
+
+    // Set error exit code (before return so the process exits after output)
+    if (isError) {
+      process.exitCode = 1;
+    }
+
+    return { data: response.body };
   },
 });

src/lib/formatters/output.ts

@@ -60,7 +60,7 @@ type WriteOutputOptions<T> = {
 /**
  * Output configuration declared on `buildCommand` for automatic rendering.
  *
- * Two forms:
+ * Three forms:
  *
  * 1. **Flag-only** — `output: "json"` — injects `--json` and `--fields` flags
  *    but does not intercept returns. Commands handle their own output.
@@ -69,14 +69,23 @@ type WriteOutputOptions<T> = {
  *    AND auto-renders the command's return value. Commands return
  *    `{ data }` or `{ data, hint }` objects.
  *
+ * 3. **JSON-only config** — `output: { json: true }` — like full config but
+ *    without a `human` formatter. Data is always serialized as JSON.
+ *
  * @typeParam T - Type of data the command returns (used by `human` formatter
  *   and serialized as-is to JSON)
  */
 export type OutputConfig<T> = {
   /** Enable `--json` and `--fields` flag injection */
   json: true;
-  /** Format data as a human-readable string for terminal output */
-  human: (data: T) => string;
+  /**
+   * Format data as a human-readable string for terminal output.
+   *
+   * When omitted the command is **JSON-only**: data is always serialized
+   * as JSON regardless of whether `--json` was passed.  The `--json` and
+   * `--fields` flags are still injected for consistency.
+   */
+  human?: (data: T) => string;
   /**
    * Top-level keys to strip from JSON output.
    *
@@ -136,7 +145,8 @@ export function renderCommandOutput(
   config: OutputConfig<any>,
   ctx: RenderContext
 ): void {
-  if (ctx.json) {
+  // JSON mode: explicit --json flag, or no human formatter (JSON-only command)
+  if (ctx.json || !config.human) {
     let jsonData = data;
     if (
       config.jsonExclude &&

test/commands/api.property.test.ts

@@ -16,12 +16,12 @@ import {
   oneof,
   property,
   record,
+  string,
   stringMatching,
   tuple,
   uniqueArray,
 } from "fast-check";
 import {
-  buildDryRunRequest,
   buildFromFields,
   extractJsonBody,
   normalizeEndpoint,
@@ -31,6 +31,7 @@ import {
   parseFieldValue,
   parseMethod,
   resolveBody,
+  resolveEffectiveHeaders,
   resolveRequestUrl,
   setNestedValue,
 } from "../../src/commands/api.js";
@@ -794,7 +795,6 @@ describe("property: resolveBody", () => {
 // Dry-run property tests
 
 /** Arbitrary for HTTP methods */
-const httpMethodArb = constantFrom("GET", "POST", "PUT", "DELETE", "PATCH");
 
 /** Arbitrary for clean API endpoint paths (no query string, for dry-run tests) */
 const dryRunEndpointArb = stringMatching(
@@ -855,61 +855,65 @@ describe("property: resolveRequestUrl", () => {
   });
 });
 
-describe("property: buildDryRunRequest", () => {
-  test("method is preserved exactly", () => {
-    fcAssert(
-      property(httpMethodArb, dryRunEndpointArb, (method, endpoint) => {
-        const request = buildDryRunRequest(method, endpoint, {});
-        expect(request.method).toBe(method);
-      }),
-      { numRuns: DEFAULT_NUM_RUNS }
-    );
+describe("property: resolveEffectiveHeaders", () => {
+  /** Arbitrary for custom header entries (non-content-type keys) */
+  const headerKeyArb = stringMatching(/^X-[A-Za-z]{1,10}$/);
+  const headerValueArb = string({ minLength: 1, maxLength: 20 });
+  const customHeadersArb = dictionary(headerKeyArb, headerValueArb, {
+    minKeys: 0,
+    maxKeys: 3,
   });
 
-  test("URL contains the endpoint", () => {
+  test("preserves all custom headers", () => {
     fcAssert(
-      property(httpMethodArb, dryRunEndpointArb, (method, endpoint) => {
-        const request = buildDryRunRequest(method, endpoint, {});
-        const normalized = endpoint.startsWith("/")
-          ? endpoint.slice(1)
-          : endpoint;
-        expect(request.url).toContain(normalized);
+      property(customHeadersArb, (custom) => {
+        const result = resolveEffectiveHeaders(custom, undefined);
+        for (const [key, value] of Object.entries(custom)) {
+          expect(result[key]).toBe(value);
+        }
       }),
       { numRuns: DEFAULT_NUM_RUNS }
     );
   });
 
-  test("headers default to empty object when undefined", () => {
+  test("auto-adds Content-Type for object bodies without it", () => {
     fcAssert(
-      property(httpMethodArb, dryRunEndpointArb, (method, endpoint) => {
-        const request = buildDryRunRequest(method, endpoint, {});
-        expect(request.headers).toEqual({});
+      property(customHeadersArb, jsonValue(), (custom, body) => {
+        // Ensure body is a non-null object (not string/number/boolean/null)
+        if (body === null || body === undefined || typeof body !== "object") {
+          return;
+        }
+        const result = resolveEffectiveHeaders(custom, body);
+        expect(result["Content-Type"]).toBe("application/json");
       }),
       { numRuns: DEFAULT_NUM_RUNS }
     );
   });
 
-  test("body defaults to null when undefined", () => {
+  test("never adds Content-Type for string bodies", () => {
     fcAssert(
-      property(httpMethodArb, dryRunEndpointArb, (method, endpoint) => {
-        const request = buildDryRunRequest(method, endpoint, {});
-        expect(request.body).toBeNull();
+      property(customHeadersArb, string(), (custom, body) => {
+        const result = resolveEffectiveHeaders(custom, body);
+        // Should not have auto-added Content-Type (only custom headers)
+        if (!custom["Content-Type"]) {
+          expect(result["Content-Type"]).toBeUndefined();
+        }
       }),
       { numRuns: DEFAULT_NUM_RUNS }
     );
   });
 
-  test("provided body is preserved", () => {
+  test("does not override explicit Content-Type", () => {
+    const contentTypeArb = constantFrom(
+      "text/plain",
+      "text/xml",
+      "application/x-www-form-urlencoded"
+    );
     fcAssert(
-      property(
-        httpMethodArb,
-        dryRunEndpointArb,
-        jsonValue(),
-        (method, endpoint, body) => {
-          const request = buildDryRunRequest(method, endpoint, { body });
-          expect(request.body).toEqual(body);
-        }
-      ),
+      property(contentTypeArb, jsonValue(), (ct, body) => {
+        const result = resolveEffectiveHeaders({ "Content-Type": ct }, body);
+        expect(result["Content-Type"]).toBe(ct);
+      }),
       { numRuns: DEFAULT_NUM_RUNS }
     );
   });