fix: api command preserves raw string responses, fix null body header divergence

Address three bot review comments:

1. String response quoting regression (Seer + BugBot): the api command
   is a raw proxy — non-JSON responses (plain text, HTML error pages)
   must not be wrapped in JSON quotes. Revert to output: 'json'
   (flag-only) and write response body imperatively via writeResponseBody,
   which writes strings directly and JSON-formats objects with --fields.

2. Null body header divergence (BugBot): resolveEffectiveHeaders had an
   extra body !== null check that rawApiRequest doesn't. For --data
   "null", dry-run would omit Content-Type while the real request adds
   it. Aligned condition to match rawApiRequest exactly:
   !(isStringBody || hasContentType) && body !== undefined.

3. Stale comment about dry-run always outputting JSON (BugBot on old
   commit 70e7f2d): the referenced code was completely rewritten in
   6980508. No action needed — will reply to dismiss.

Also reverts OutputConfig.human back to required (the JSON-only config
form is no longer needed since the api command doesn't use it).

Author: BYK

src/commands/api.ts

@@ -27,9 +27,9 @@ type ApiFlags = {
   readonly silent: boolean;
   readonly verbose: boolean;
   readonly "dry-run": boolean;
-  /** Injected by buildCommand via output: { json: true } */
+  /** Injected by buildCommand via output: "json" */
   readonly json: boolean;
-  /** Injected by buildCommand via output: { json: true } */
+  /** Injected by buildCommand via output: "json" */
   readonly fields?: string[];
 };
 
@@ -864,6 +864,31 @@ export function writeResponseHeaders(
   stdout.write("\n");
 }
 
+/**
+ * Write API response body to stdout.
+ *
+ * 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.
+ *
+ * @internal Exported for testing
+ */
+export function writeResponseBody(
+  stdout: Writer,
+  body: unknown,
+  fields?: string[]
+): void {
+  if (body === null || body === undefined) {
+    return;
+  }
+
+  if (typeof body === "object") {
+    writeJson(stdout, body, fields);
+  } else {
+    stdout.write(`${String(body)}\n`);
+  }
+}
+
 /**
  * Write verbose request output (curl-style format)
  * @internal Exported for testing
@@ -933,13 +958,14 @@ export function resolveEffectiveHeaders(
   customHeaders: Record<string, string> | undefined,
   body: unknown
 ): Record<string, string> {
+  // Mirror rawApiRequest exactly: auto-add Content-Type for any non-string,
+  // non-undefined body when no Content-Type was explicitly provided.
+  const isStringBody = typeof body === "string";
   const headers = { ...(customHeaders ?? {}) };
-  if (
-    body !== undefined &&
-    body !== null &&
-    typeof body !== "string" &&
-    !Object.keys(headers).some((k) => k.toLowerCase() === "content-type")
-  ) {
+  const hasContentType = Object.keys(headers).some(
+    (k) => k.toLowerCase() === "content-type"
+  );
+  if (!(isStringBody || hasContentType) && body !== undefined) {
     headers["Content-Type"] = "application/json";
   }
   return headers;
@@ -1068,7 +1094,7 @@ export async function resolveBody(
 // Command Definition
 
 export const apiCommand = buildCommand({
-  output: { json: true },
+  output: "json",
   docs: {
     brief: "Make an authenticated API request",
     fullDescription:
@@ -1191,16 +1217,20 @@ export const apiCommand = buildCommand({
         ? parseHeaders(flags.header)
         : undefined;
 
+    // Dry-run mode: preview the request that would be sent
     // Dry-run mode: preview the request that would be sent
     if (flags["dry-run"]) {
-      return {
-        data: {
+      writeJson(
+        stdout,
+        {
           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
@@ -1225,21 +1255,22 @@ export const apiCommand = buildCommand({
       return;
     }
 
-    // Output response headers when requested (side-effect before body)
+    // Output response headers when requested
     if (flags.verbose) {
       writeVerboseResponse(stdout, response.status, response.headers);
     } else if (flags.include) {
       writeResponseHeaders(stdout, response.status, response.headers);
     }
 
-    // Error responses: Stricli overwrites process.exitCode after the
-    // command returns, so we must use process.exit(1) directly.
-    // Return { data } for success so the output wrapper renders it.
+    // 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) {
-      writeJson(stdout, response.body, flags.fields);
       process.exit(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.
  *
- * Three forms:
+ * Two forms:
  *
  * 1. **Flag-only** — `output: "json"` — injects `--json` and `--fields` flags
  *    but does not intercept returns. Commands handle their own output.
@@ -69,23 +69,14 @@ 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.
-   *
-   * 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;
+  /** Format data as a human-readable string for terminal output */
+  human: (data: T) => string;
   /**
    * Top-level keys to strip from JSON output.
    *
@@ -145,8 +136,7 @@ export function renderCommandOutput(
   config: OutputConfig<any>,
   ctx: RenderContext
 ): void {
-  // JSON mode: explicit --json flag, or no human formatter (JSON-only command)
-  if (ctx.json || !config.human) {
+  if (ctx.json) {
     let jsonData = data;
     if (
       config.jsonExclude &&

test/commands/api.test.ts

@@ -28,6 +28,7 @@ import {
   resolveEffectiveHeaders,
   resolveRequestUrl,
   setNestedValue,
+  writeResponseBody,
   writeResponseHeaders,
   writeVerboseRequest,
   writeVerboseResponse,
@@ -912,6 +913,54 @@ 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");
+  });
+
+  test("writes string directly without JSON quoting", () => {
+    const writer = createMockWriter();
+    writeResponseBody(writer, "plain text response");
+    expect(writer.output).toBe("plain text response\n");
+  });
+
+  test("writes number as string", () => {
+    const writer = createMockWriter();
+    writeResponseBody(writer, 42);
+    expect(writer.output).toBe("42\n");
+  });
+
+  test("does not write null", () => {
+    const writer = createMockWriter();
+    writeResponseBody(writer, null);
+    expect(writer.output).toBe("");
+  });
+
+  test("does not write undefined", () => {
+    const writer = createMockWriter();
+    writeResponseBody(writer, undefined);
+    expect(writer.output).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" });
+  });
+});
+
 describe("writeVerboseRequest", () => {
   test("writes method and endpoint", () => {
     const writer = createMockWriter();
@@ -1111,6 +1160,16 @@ describe("resolveEffectiveHeaders", () => {
     const headers = resolveEffectiveHeaders(undefined, undefined);
     expect(headers).toEqual({});
   });
+
+  test("adds Content-Type for null body (matches rawApiRequest)", () => {
+    const headers = resolveEffectiveHeaders(undefined, null);
+    expect(headers["Content-Type"]).toBe("application/json");
+  });
+
+  test("does not add Content-Type for undefined body", () => {
+    const headers = resolveEffectiveHeaders(undefined, undefined);
+    expect(headers["Content-Type"]).toBeUndefined();
+  });
 });
 
 // --data/-d and JSON auto-detection (CLI-AF)