fix: display CLI help text on stdout instead of stderr

[konard]

Summary

Fixed the color issue with help text when calling agent auth without a subcommand.

Problem

When running agent auth without specifying a subcommand (like login, logout, etc.), the help text was appearing in red color in terminals. This happened because:

1. The help text was being written to stderr via outputError(), and many terminals display stderr output in red
2. The ANSI color codes from yargs were included in the output
3. The exit code was 1 (error), even though displaying help is not an error condition

Solution

• Added a new outputHelp() function in js/src/cli/output.ts that writes to stdout with type 'status' (informational, not error)
• Modified the .fail() handler in js/src/index.js to use outputHelp() instead of outputError() for validation messages (no-subcommand case)
• Strip ANSI color codes from yargs.help() output using stripAnsi()
• Changed exit code from 1 to 0 since displaying help is not an error

Audit Results

All outputError() / writeStderr / process.stderr usages in the codebase were audited:

Location	Usage	Status
index.js .fail() handler (msg case)	Help/validation text	Fixed → stdout
index.js .fail() handler (err case)	Command handler errors	Correct (stderr)
index.js uncaughtException/unhandledRejection	Fatal errors	Correct (stderr)
index.js AuthenticationError, FileNotFound	Real errors	Correct (stderr)
index.js ValidationError (--disable-stdin, etc.)	Config errors	Correct (stderr)
continuous-mode.js SessionNotFound	Real errors	Correct (stderr)
session/agent.js ToolExecutionError	Real errors	Correct (stderr)
json-standard/index.ts event output	Errors → stderr, rest → stdout	Correct
cmd/export.ts @clack/prompts	Interactive UI on stderr (pipe-friendly)	Correct (intentional)

Conclusion: Only the .fail() handler's help text case was incorrectly using stderr. All other stderr usages are for genuine errors and are correct.

Industry Standard Comparison

Tool	No Subcommand	Destination
git	2126 bytes stdout, 0 bytes stderr	STDOUT
gh (GitHub CLI)	2442 bytes stdout, 0 bytes stderr	STDOUT
npm	1268 bytes stdout, 0 bytes stderr	STDOUT
agent auth (after fix)	609 bytes stdout, 0 bytes stderr	STDOUT

Changes

• js/src/cli/output.ts: Added outputHelp() function that writes to stdout
• js/src/index.js: Changed .fail() handler to use outputHelp() + stripAnsi() for validation messages
• js/.changeset/fix-auth-help-stdout.md: Changeset for patch release
• experiments/test-help-stdout.sh: Test script verifying stdout output
• experiments/test-help-vs-error.sh: Test script verifying help vs error distinction

Testing

• ✅ agent auth help text goes to stdout (609 bytes), stderr empty (0 bytes)
• ✅ agent mcp help text goes to stdout (427 bytes), stderr empty (0 bytes)
• ✅ agent --help continues to work correctly
• ✅ No ANSI color codes in output
• ✅ Exit code is 0 (informational, not error)
• ✅ All existing unit tests pass (19 tests)
• ✅ ESLint passes
• ✅ Prettier formatting check passes
• ✅ File size check passes

Fixes #77

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $2.931474 USD
• Calculated by Anthropic: unknown
• Difference: unknown
  📎 Log file uploaded as GitHub Gist (489KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

How other CLI tools handle these cases? Is display of help is error or success?

[konard]

🤖 AI Work Session Started

Starting automated work session at 2025-12-21T20:07:35.618Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

Answer: Help display should go to STDOUT (success case)

I researched how popular CLI tools handle this scenario. Here are the findings:

Popular CLI Tools Behavior

When called without a subcommand, these tools display help on stdout:

git        → stdout: 2126 bytes, stderr: 0 bytes ✅ STDOUT
gh         → stdout: 2442 bytes, stderr: 0 bytes ✅ STDOUT  
npm        → stdout: 1268 bytes, stderr: 0 bytes ✅ STDOUT
agent auth → stdout: 2242 bytes, stderr: 0 bytes ✅ STDOUT (after our fix)

Invalid Subcommand vs No Subcommand

CLI tools distinguish between these two cases:

Case 1: No subcommand (user needs help)

• git → STDOUT (2126 bytes help text)
• gh → STDOUT (2442 bytes help text)

Case 2: Invalid subcommand (actual error)

• git invalidcmd → STDERR (61 bytes error)
• gh invalidcmd → STDERR (378 bytes error)

Why STDOUT is Correct

1. Industry Standard: git, gh, and npm all use stdout for help display
2. Semantic Correctness: Help display is informational (stdout), not an error condition (stderr)
3. User Intent: When typing agent auth, users are seeking information, not encountering an error
4. Terminal Behavior: Many terminals show stderr in red, which is inappropriate for help text

Conclusion

Help display is a success case - the tool is successfully showing the user what they need. Our fix aligns with how leading CLI tools (git, GitHub CLI, npm) handle this scenario.

Full research findings are documented in experiments/cli-help-research/RESEARCH-FINDINGS.md

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $1.170437 USD
• Calculated by Anthropic: $0.877703 USD
• Difference: $-0.292734 (-25.01%)
  📎 Log file uploaded as GitHub Gist (237KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

Resolve merge conflicts, and ensure we don't ever show informational messages as stderr, use in all places stdout unless it is critical error, regular error or warning.

Ensure all changes are correct, consistent, validated, tested and fully meet all discussed requirements (check issue description and all comments in issue and in pull request). Ensure all CI/CD checks pass.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-02-13T12:01:18.352Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

[konard]

🤖 Solution Draft Log

Changes Made

1. Resolved merge conflicts by rebasing on current main (0.9.0) — the old src/index.js was moved to js/src/index.js and the codebase was significantly restructured since the initial fix.

2. Audited all stderr usage across the codebase to ensure informational messages use stdout:

   • Only the .fail() handler's help text case was incorrectly using stderr
   • All other stderr usages are for genuine errors (uncaught exceptions, auth errors, file not found, session not found, tool execution errors) — these are correct
   • The @clack/prompts stderr usage in export.ts is intentional (interactive UI on stderr for pipe-friendly data output)

3. Applied the fix:

   • Added outputHelp() function in js/src/cli/output.ts → writes to stdout with type 'status'
   • Modified .fail() handler to use outputHelp() + stripAnsi() instead of outputError()
   • Changed exit code from 1 to 0 for help display
   • Added changeset for patch release

4. Verified:

   • agent auth → stdout: 609 bytes, stderr: 0 bytes ✅
   • agent mcp → stdout: 427 bytes, stderr: 0 bytes ✅
   • agent --help → stdout: 4630 bytes, stderr: 0 bytes ✅
   • All CI checks passing (lint, format, unit tests on Ubuntu/macOS/Windows) ✅

---

Working session completed.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $5.172338
• Calculated by Anthropic: $10.520710 USD
• Difference: $5.348372 (+103.40%)
  📎 Log file uploaded as Gist (688KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.