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

@@ -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 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,16 @@ 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.
-    if (isError) {
-      process.exit(1);
-    }
+    return {
+      data: response.body,
+      exitCode: isError ? 1 : undefined,
+    };
   },
 });

src/lib/command.ts

@@ -338,6 +338,12 @@ export function buildCommand<
       json: Boolean(flags.json),
       fields: flags.fields as string[] | undefined,
     });
+
+    // Honor exit code AFTER rendering — Stricli overwrites process.exitCode
+    // after the func returns, so we must use process.exit() directly.
+    if (typeof value.exitCode === "number") {
+      process.exit(value.exitCode);
+    }
   }
 
   /**

src/lib/formatters/output.ts

@@ -102,6 +102,15 @@ export type CommandOutput<T> = {
   data: T;
   /** Hint line appended after human output (suppressed in JSON mode) */
   hint?: string;
+  /**
+   * Exit code to set after rendering output.
+   *
+   * Stricli overwrites `process.exitCode` after the command returns,
+   * so commands that need non-zero exit (e.g. API error responses)
+   * must signal it here. The wrapper calls `process.exit()` after
+   * rendering is complete.
+   */
+  exitCode?: number;
 };
 
 /**

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

test/lib/command.test.ts

@@ -1236,4 +1236,86 @@ describe("buildCommand return-based output", () => {
     expect(jsonRaw).not.toContain("Detected from");
     expect(JSON.parse(jsonRaw)).toEqual({ org: "sentry" });
   });
+
+  test("exitCode calls process.exit after rendering", async () => {
+    let exitCalledWith: number | undefined;
+    const originalExit = process.exit;
+
+    const command = buildCommand<
+      { json: boolean; fields?: string[] },
+      [],
+      TestContext
+    >({
+      docs: { brief: "Test" },
+      output: {
+        json: true,
+        human: (d: { error: string }) => `Error: ${d.error}`,
+      },
+      parameters: {},
+      func(this: TestContext) {
+        return { data: { error: "not found" }, exitCode: 1 };
+      },
+    });
+
+    const routeMap = buildRouteMap({
+      routes: { test: command },
+      docs: { brief: "Test app" },
+    });
+    const app = buildApplication(routeMap, { name: "test" });
+    const ctx = createTestContext();
+
+    // Mock process.exit to capture the call without actually exiting
+    process.exit = ((code?: number) => {
+      exitCalledWith = code;
+    }) as typeof process.exit;
+
+    try {
+      await run(app, ["test"], ctx as TestContext);
+      expect(exitCalledWith).toBe(1);
+      // Output was rendered BEFORE exit
+      expect(ctx.output.join("")).toContain("Error: not found");
+    } finally {
+      process.exit = originalExit;
+    }
+  });
+
+  test("exitCode is not called when undefined", async () => {
+    let exitCalled = false;
+    const originalExit = process.exit;
+
+    const command = buildCommand<
+      { json: boolean; fields?: string[] },
+      [],
+      TestContext
+    >({
+      docs: { brief: "Test" },
+      output: {
+        json: true,
+        human: (d: { ok: boolean }) => `OK: ${d.ok}`,
+      },
+      parameters: {},
+      func(this: TestContext) {
+        return { data: { ok: true } };
+      },
+    });
+
+    const routeMap = buildRouteMap({
+      routes: { test: command },
+      docs: { brief: "Test app" },
+    });
+    const app = buildApplication(routeMap, { name: "test" });
+    const ctx = createTestContext();
+
+    process.exit = (() => {
+      exitCalled = true;
+    }) as typeof process.exit;
+
+    try {
+      await run(app, ["test"], ctx as TestContext);
+      expect(exitCalled).toBe(false);
+      expect(ctx.output.join("")).toContain("OK: true");
+    } finally {
+      process.exit = originalExit;
+    }
+  });
 });