fix(setup): diagnose display-only fallbacks in debug mode

[yuhaouno]

setup silently falls back when its summary-only profile reread fails or an agent-install output line is not JSON. Even with --debug, operators cannot tell why endpoint reporting fell back or an install result was ignored. This adds stderr diagnostics for those two remaining init.ts catch sites from #186.

Refs #186

A local best-effort diagnostic helper also protects the existing identity-lookup diagnostic: a failing stderr sink must not turn an already-recovered, display-only failure into a failed setup. Non-debug output, endpoint precedence, install-result aggregation, and credential/configuration failure handling are preserved. Non-JSON output is identified by context only; neither the captured line nor a JSON parser error that may quote it is logged.

This PR is based directly on main and is independent of #350 (duplicate-name lookup diagnostics). The umbrella issue remains open.

Validation on macOS / Node 24.16.0:

• 9 new regression tests exercise profile, install-output, and identity fallback paths in JSON/text mode and with a throwing diagnostic sink. Five fail against unmodified main; all pass with this change.
• Setup unit tests: 93 passed.
• Full suite: 3,705 passed, 2 skipped across 100 test files; coverage: lines/statements 89.99%, branches 88.04%, functions 92.40%.
• End-to-end suite after build: 101 passed, 1 skipped.
• Build, CLI version smoke check, TypeScript, Prettier, and ESLint pass (ESLint has the existing unused-disable warnings).
• Tests run with the host's NO_COLOR=1 removed because the existing ANSI ticker tests assume color is enabled.

Fork CI may need maintainer approval before Linux/Windows checks run.

Summary by CodeRabbit

• Documentation
  • Clarified that --debug reports setup fallback diagnostics to stderr, while normal output and fallback behavior remain unchanged.
• Tests
  • Added coverage for debug diagnostics across setup fallback scenarios, including checks that setup completes if diagnostic reporting fails.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: TestSprite/testsprite-cli/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 82bae11d-94f9-404e-bc68-6af01fc81b5d

📥 Commits

Reviewing files that changed from the base of the PR and between 14ac000 and f1aba45.

📒 Files selected for processing (3)

• DOCUMENTATION.md
• src/commands/init.debug.spec.ts
• src/commands/init.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

Walkthrough

Setup recovery paths now report selected lookup failures and ignored non-JSON agent-install output to stderr when --debug is enabled. Fallback behavior and the JSON summary remain unchanged.

Changes

Setup recovery diagnostics

Layer / File(s)	Summary
Debug-only recovery diagnostics src/commands/init.ts, src/commands/init.debug.spec.ts, DOCUMENTATION.md	A shared helper emits diagnostics only when --debug is enabled and suppresses errors from the diagnostic sink. Profile and identity lookup fallbacks remain in place, and non-JSON agent-install output remains ignored. Tests cover debug and non-debug output, selected JSON fields, and a throwing diagnostic sink. Documentation describes the behavior.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Merge Risk: ⚪ Minimal · up to f1aba

Setup’s fallback behavior and summary remain unchanged, with additional diagnostics only in debug mode. No actionable merge-blocking risk is established.

Security Architecture Review

Security architecture risk: 🔵 Low · up to f1aba

The change is limited to opt-in debug output, and no sensitive-data exposure has been established. One new diagnostic includes the text of a credential-read error, whose possible contents remain uncertain.

Retained concerns

• Low · security · inferred: The new profile-lookup diagnostic forwards an unchecked credential-read exception message to debug stderr. Disclosure depends on what that exception can contain; sensitive content has not been demonstrated.

Security review details

Security Blast Radius

• inferred — Any new exposure is confined to stderr recipients of a setup invocation using --debug, including environments that retain CLI logs; the change does not add a network or credential-write destination.

Security Findings and Attack Paths

• observed — The deferred /me error-content question does not establish a finding introduced by this PR: the identity fallback already wrote the caught error message under --debug. Whether the service supplies sensitive message content remains unknown.

Trust Boundaries and Controls

• observed — The profile-summary path now carries a readProfile exception into debug stderr. The helper gates output on --debug and catches sink failures, but does not filter the exception message.

Resilience and Maintainability Implications

• observed — Credential validation and persistence precede the display-only identity fallback. A failed diagnostic sink is suppressed there, while agent-install failures remain separately propagated.

Hardening Proposals

• proposed — If credential-read exceptions cannot be shown to exclude sensitive content, use a fixed diagnostic or a narrowly classified reason for that fallback rather than forwarding arbitrary exception text.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding diagnostics for setup fallbacks in debug mode.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}