refactor: api command fully return-based, remove writeResponseBody

Both dry-run and normal response paths now return { data } through the
output system. No more imperative writeJson/writeResponseBody calls.

Changes:
- Add exitCode field to CommandOutput<T> — the buildCommand wrapper
  calls process.exit() after rendering when set. This works around
  Stricli overwriting process.exitCode after the command returns.
- Add formatApiResponse human formatter — preserves raw strings (plain
  text, HTML error pages) without JSON quoting, JSON-formats objects.
- Api command uses output: { json: true, human: formatApiResponse }
  instead of flag-only output: 'json'.
- Error responses return { data: body, exitCode: 1 } instead of
  calling process.exit(1) directly after imperative writes.
- Remove writeResponseBody function and writeJson import from api.ts.

Author: BYK

src/commands/api.ts

@@ -8,8 +8,7 @@
 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 { OutputError, ValidationError } from "../lib/errors.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 config */
   readonly json: boolean;
-  /** Injected by buildCommand via output: "json" */
+  /** Injected by buildCommand via output config */
   readonly fields?: string[];
 };
 
@@ -865,28 +864,23 @@ export function writeResponseHeaders(
 }
 
 /**
- * Write API response body to stdout.
+ * Format an API response body for human-readable output.
  *
- * Preserves raw strings (plain text, HTML error pages) without JSON quoting.
- * Objects/arrays are JSON-formatted with optional `--fields` filtering.
- * Null/undefined bodies produce no output.
+ * The api command is a raw proxy — the response body is the output.
+ * Objects/arrays are JSON-formatted; strings (plain text, HTML error
+ * pages) pass through without JSON quoting; null/undefined produce
+ * no output.
  *
  * @internal Exported for testing
  */
-export function writeResponseBody(
-  stdout: Writer,
-  body: unknown,
-  fields?: string[]
-): void {
+export function formatApiResponse(body: unknown): string {
   if (body === null || body === undefined) {
-    return;
+    return "";
   }
-
   if (typeof body === "object") {
-    writeJson(stdout, body, fields);
-  } else {
-    stdout.write(`${String(body)}\n`);
+    return JSON.stringify(body, null, 2);
   }
+  return String(body);
 }
 
 /**
@@ -1094,7 +1088,7 @@ export async function resolveBody(
 // Command Definition
 
 export const apiCommand = buildCommand({
-  output: "json",
+  output: { json: true, human: formatApiResponse },
   docs: {
     brief: "Make an authenticated API request",
     fullDescription:
@@ -1219,17 +1213,14 @@ export const apiCommand = buildCommand({
 
     // Dry-run mode: preview the request that would be sent
     if (flags["dry-run"]) {
-      writeJson(
-        stdout,
-        {
+      return {
+        data: {
           method: flags.method,
           url: resolveRequestUrl(normalizedEndpoint, params),
           headers: resolveEffectiveHeaders(headers, body),
           body: body ?? null,
         },
-        flags.fields
-      );
-      return;
+      };
     }
 
     // Verbose mode: show request details before the response
@@ -1254,22 +1245,19 @@ export const apiCommand = buildCommand({
       return;
     }
 
-    // Output response headers when requested
+    // Output response headers when requested (side-effect before body)
     if (flags.verbose) {
       writeVerboseResponse(stdout, response.status, response.headers);
     } else if (flags.include) {
       writeResponseHeaders(stdout, response.status, response.headers);
     }
 
-    // Write response body — preserve raw strings, JSON-format objects.
-    // The api command is a raw proxy; non-JSON responses (plain text,
-    // HTML error pages) must not be wrapped in JSON string quotes.
-    writeResponseBody(stdout, response.body, flags.fields);
-
-    // Error exit: Stricli overwrites process.exitCode after the command
-    // returns, so we must call process.exit(1) directly.
+    // Error responses: throw so the wrapper renders the body then exits 1.
+    // The body is still useful (API error details), just indicates failure.
     if (isError) {
-      process.exit(1);
+      throw new OutputError(response.body);
     }
+
+    return { data: response.body };
   },
 });

src/lib/command.ts

@@ -36,6 +36,7 @@ import {
   buildCommand as stricliCommand,
   numberParser as stricliNumberParser,
 } from "@stricli/core";
+import { OutputError } from "./errors.js";
 import { parseFieldsList } from "./formatters/json.js";
 import {
   type CommandOutput,
@@ -379,19 +380,43 @@ export function buildCommand<
       setArgsContext(args);
     }
 
+    // OutputError handler: render data through the output system, then
+    // exit with the error's code. Stricli overwrites process.exitCode = 0
+    // after successful returns, so process.exit() is the only way to
+    // preserve a non-zero code. This lives in the framework — commands
+    // simply `throw new OutputError(data)`.
+    const handleOutputError = (err: unknown): never => {
+      if (err instanceof OutputError && outputConfig) {
+        handleReturnValue(
+          this,
+          { data: err.data } as CommandOutput<unknown>,
+          cleanFlags
+        );
+        process.exit(err.exitCode);
+      }
+      throw err;
+    };
+
     // Call original and intercept data returns.
     // Commands with output config return { data, hint? };
     // the wrapper renders automatically. Void returns are ignored.
-    const result = originalFunc.call(
-      this,
-      cleanFlags as FLAGS,
-      ...(args as unknown as ARGS)
-    );
+    let result: ReturnType<typeof originalFunc>;
+    try {
+      result = originalFunc.call(
+        this,
+        cleanFlags as FLAGS,
+        ...(args as unknown as ARGS)
+      );
+    } catch (err) {
+      handleOutputError(err);
+    }
 
     if (result instanceof Promise) {
-      return result.then((resolved) => {
-        handleReturnValue(this, resolved, cleanFlags);
-      }) as ReturnType<typeof originalFunc>;
+      return result
+        .then((resolved) => {
+          handleReturnValue(this, resolved, cleanFlags);
+        })
+        .catch(handleOutputError) as ReturnType<typeof originalFunc>;
     }
 
     handleReturnValue(this, result, cleanFlags);

src/lib/errors.ts

@@ -130,6 +130,26 @@ export class ConfigError extends CliError {
   }
 }
 
+/**
+ * Thrown when a command produces valid output but should exit non-zero.
+ *
+ * Unlike other errors, the output data is rendered to stdout (not stderr)
+ * through the normal output system — the `buildCommand` wrapper catches
+ * this before it reaches the global error handler. Think "HTTP 404 body":
+ * useful data, but the operation itself failed.
+ *
+ * @param data - The output data to render (same type as CommandOutput.data)
+ */
+export class OutputError extends CliError {
+  readonly data: unknown;
+
+  constructor(data: unknown) {
+    super("", 1);
+    this.name = "OutputError";
+    this.data = data;
+  }
+}
+
 const DEFAULT_CONTEXT_ALTERNATIVES = [
   "Run from a directory with a Sentry-configured project",
   "Set SENTRY_ORG and SENTRY_PROJECT (or SENTRY_DSN) environment variables",

test/commands/api.test.ts

@@ -16,6 +16,7 @@ import {
   buildRawQueryParams,
   dataToQueryParams,
   extractJsonBody,
+  formatApiResponse,
   normalizeEndpoint,
   normalizeFields,
   parseDataBody,
@@ -28,7 +29,6 @@ import {
   resolveEffectiveHeaders,
   resolveRequestUrl,
   setNestedValue,
-  writeResponseBody,
   writeResponseHeaders,
   writeVerboseRequest,
   writeVerboseResponse,
@@ -913,51 +913,33 @@ describe("writeResponseHeaders", () => {
   });
 });
 
-describe("writeResponseBody", () => {
-  test("writes JSON object with pretty-printing", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, { key: "value", num: 42 });
-    expect(writer.output).toBe('{\n  "key": "value",\n  "num": 42\n}\n');
-  });
-
-  test("writes JSON array with pretty-printing", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, [1, 2, 3]);
-    expect(writer.output).toBe("[\n  1,\n  2,\n  3\n]\n");
+describe("formatApiResponse", () => {
+  test("formats JSON object with pretty-printing", () => {
+    expect(formatApiResponse({ key: "value", num: 42 })).toBe(
+      '{\n  "key": "value",\n  "num": 42\n}'
+    );
   });
 
-  test("writes string directly without JSON quoting", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, "plain text response");
-    expect(writer.output).toBe("plain text response\n");
+  test("formats JSON array with pretty-printing", () => {
+    expect(formatApiResponse([1, 2, 3])).toBe("[\n  1,\n  2,\n  3\n]");
   });
 
-  test("writes number as string", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, 42);
-    expect(writer.output).toBe("42\n");
+  test("formats string directly without JSON quoting", () => {
+    expect(formatApiResponse("plain text response")).toBe(
+      "plain text response"
+    );
   });
 
-  test("does not write null", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, null);
-    expect(writer.output).toBe("");
+  test("formats number as string", () => {
+    expect(formatApiResponse(42)).toBe("42");
   });
 
-  test("does not write undefined", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, undefined);
-    expect(writer.output).toBe("");
+  test("returns empty string for null", () => {
+    expect(formatApiResponse(null)).toBe("");
   });
 
-  test("applies --fields filtering to objects", () => {
-    const writer = createMockWriter();
-    writeResponseBody(writer, { id: "1", name: "test", extra: "data" }, [
-      "id",
-      "name",
-    ]);
-    const parsed = JSON.parse(writer.output);
-    expect(parsed).toEqual({ id: "1", name: "test" });
+  test("returns empty string for undefined", () => {
+    expect(formatApiResponse(undefined)).toBe("");
   });
 });