fix(cli): route interactive prompts and prelude to stderr (keep stdout pure) (#31)

Interactive prompts (`prompt.ts` — the API-key prompt during `setup`/`auth
configure`, the target prompt during `agent install`) wrote the question and
masking to STDOUT, and the "Configuring profile …" prelude defaulted to
stdout too. On the interactive path that mixes UI text into stdout — and
under `--output json` it breaks the contract that stdout is a single JSON
document, so a consumer doing `JSON.parse(stdout)` fails.

Default both to stderr: prompts and informational preludes are interactive
UI, not result data. stdout now carries only the command's result (the §8.1
stdout-purity principle the repo already enforces elsewhere). stderr is still
the user's TTY, so prompts remain visible; the secret is still never echoed.
Callers that inject explicit streams are unaffected.

Adds regression tests: promptText writes the question to stderr by default,
and the configure prelude lands on stderr (not the result stdout).

Author: Davidson3556

src/commands/auth.test.ts

@@ -278,6 +278,35 @@ describe('runConfigure', () => {
     expect(capture.prelude.join('')).toContain('Configuring profile "default"');
   });
 
+  it('routes the interactive prelude to stderr by default, keeping stdout for the result', async () => {
+    // Regression: the prelude used to default to process.stdout, polluting the
+    // result stream (and the JSON document under --output json). With no
+    // injected preludeWrite/stderr, the default must land on stderr, not stdout.
+    const stdout: string[] = [];
+    const errChunks: string[] = [];
+    const origErr = process.stderr.write.bind(process.stderr);
+    (process.stderr as unknown as { write: (c: string) => boolean }).write = c => {
+      errChunks.push(String(c));
+      return true;
+    };
+    try {
+      await runConfigure(
+        { profile: 'default', output: 'text', debug: false, fromEnv: false },
+        {
+          stdout: line => stdout.push(line),
+          prompt: { secret: vi.fn(async () => 'sk-typed') },
+          fetchImpl: meOkFetch,
+          credentialsPath,
+          env: {},
+        },
+      );
+    } finally {
+      (process.stderr as unknown as { write: typeof origErr }).write = origErr;
+    }
+    expect(errChunks.join('')).toContain('Configuring profile "default"');
+    expect(stdout.join('\n')).not.toContain('Configuring profile');
+  });
+
   it('interactive path resolves the endpoint from TESTSPRITE_API_URL without prompting', async () => {
     const { capture, deps } = makeCapture();
     const prompt = { secret: vi.fn(async () => 'sk-typed') };

src/commands/auth.ts

@@ -75,7 +75,10 @@ export async function runConfigure(opts: ConfigureOptions, deps: AuthDeps = {}):
   const env = deps.env ?? process.env;
   const credentialsPath = deps.credentialsPath ?? defaultCredentialsPath();
   const out = makeOutput(opts.output, deps);
-  const prelude = deps.preludeWrite ?? ((chunk: string) => process.stdout.write(chunk));
+  // The "Configuring profile …" prelude is informational, not result data, so
+  // it defaults to stderr — stdout stays a pure result stream (the configured
+  // JSON/text), which matters under `--output json` (§8.1 stdout purity).
+  const prelude = deps.preludeWrite ?? ((chunk: string) => process.stderr.write(chunk));
   const stderr = deps.stderr ?? ((line: string) => process.stderr.write(`${line}\n`));
 
   // Normalize the env endpoint: an empty / whitespace-only TESTSPRITE_API_URL is

src/lib/prompt.test.ts

@@ -69,6 +69,33 @@ describe('promptText', () => {
     const output = new CaptureStream();
     expect(await promptText('? ', { input, output })).toBe('eof-no-newline');
   });
+
+  it('writes the question to stderr by default — keeps stdout pure for --output json', async () => {
+    // Regression: prompts used to default to stdout, which polluted the JSON
+    // result on the interactive setup/configure path. Interactive UI belongs
+    // on stderr. Manually swap the global stream writers (prompt reads
+    // process.stderr/stdout at call time, so this is reliably intercepted).
+    const errChunks: string[] = [];
+    const outChunks: string[] = [];
+    const origErr = process.stderr.write.bind(process.stderr);
+    const origOut = process.stdout.write.bind(process.stdout);
+    (process.stderr as unknown as { write: (c: string) => boolean }).write = c => {
+      errChunks.push(String(c));
+      return true;
+    };
+    (process.stdout as unknown as { write: (c: string) => boolean }).write = c => {
+      outChunks.push(String(c));
+      return true;
+    };
+    try {
+      await promptText('Q: ', { input: Readable.from(['x\n']) }); // no output → default
+    } finally {
+      (process.stderr as unknown as { write: typeof origErr }).write = origErr;
+      (process.stdout as unknown as { write: typeof origOut }).write = origOut;
+    }
+    expect(errChunks.join('')).toContain('Q: ');
+    expect(outChunks.join('')).not.toContain('Q: ');
+  });
 });
 
 describe('promptSecret (non-TTY behavior)', () => {
@@ -88,6 +115,35 @@ describe('promptSecret (non-TTY behavior)', () => {
     expect(written).not.toContain('sk-hidden-12345');
   });
 
+  it('writes the prompt to stderr by default — keeps stdout pure for --output json', async () => {
+    // Same regression as promptText: the secret prompt is interactive UI and
+    // must default to stderr so stdout carries only the command result. Manual
+    // stream swap (vi.spyOn does not intercept process.stderr.write here).
+    const errChunks: string[] = [];
+    const outChunks: string[] = [];
+    const origErr = process.stderr.write.bind(process.stderr);
+    const origOut = process.stdout.write.bind(process.stdout);
+    (process.stderr as unknown as { write: (c: string) => boolean }).write = c => {
+      errChunks.push(String(c));
+      return true;
+    };
+    (process.stdout as unknown as { write: (c: string) => boolean }).write = c => {
+      outChunks.push(String(c));
+      return true;
+    };
+    try {
+      await promptSecret('Key: ', { input: Readable.from(['sk-x\n']) }); // no output → default
+    } finally {
+      (process.stderr as unknown as { write: typeof origErr }).write = origErr;
+      (process.stdout as unknown as { write: typeof origOut }).write = origOut;
+    }
+    expect(errChunks.join('')).toContain('Key: ');
+    expect(outChunks.join('')).not.toContain('Key: ');
+    // The typed secret is never echoed to either real stream.
+    expect(errChunks.join('')).not.toContain('sk-x');
+    expect(outChunks.join('')).not.toContain('sk-x');
+  });
+
   it('honors DEL/backspace before submission', async () => {
     const DEL = String.fromCharCode(0x7f);
     const input = Readable.from([`abc${DEL}d\n`]);

src/lib/prompt.ts

@@ -15,14 +15,20 @@ const pendingPromptInput = new WeakMap<NodeJS.ReadableStream, string>();
 
 export async function promptText(question: string, streams: PromptStreams = {}): Promise<string> {
   const input = streams.input ?? process.stdin;
-  const output = streams.output ?? process.stdout;
+  // Prompts are interactive UI, not data — write the question (and any echo)
+  // to stderr so stdout carries only the command's result. This keeps
+  // `--output json` stdout a single pure JSON document even on the interactive
+  // setup / configure path (§8.1 stdout purity). stderr is still the user's
+  // TTY, so the prompt remains visible.
+  const output = streams.output ?? process.stderr;
   output.write(question);
   return readLine(input, output, false);
 }
 
 export async function promptSecret(question: string, streams: PromptStreams = {}): Promise<string> {
   const input = streams.input ?? process.stdin;
-  const output = streams.output ?? process.stdout;
+  // See promptText: interactive prompt + masking go to stderr, not stdout.
+  const output = streams.output ?? process.stderr;
   output.write(question);
 
   const inputAsTTY = input as Readable & RawModeCapable;