feat: detect non-interactive terminals and fail gracefully

[nickprotop]

Summary

• Add early TTY detection via isatty() P/Invoke — throws TerminalNotSupportedException before entering raw mode if stdin/stdout is piped or redirected
• Add post-initialization DSR verification — confirms terminal actually responds to ANSI escape sequences after alternate screen buffer is activated
• Make Stop() robust to partial Start() initialization (try/catch around Console calls that may fail)
• Restore suppressed signals (SIGINT, SIGTSTP) when Start() throws, so the caller's terminal works normally
• SIGQUIT (Ctrl+\) is intentionally never suppressed, serving as emergency exit

Fixes #12

Test plan

• dotnet build SharpConsoleUI/SharpConsoleUI.csproj — 0 warnings, 0 errors
• dotnet test SharpConsoleUI.Tests/SharpConsoleUI.Tests.csproj — 2541/2541 passing
• Normal terminal — app starts normally (no regression)
• Piped stdout (dotnet run --project Example | cat) — throws TerminalNotSupportedException immediately
• Piped stdin (echo "" | dotnet run --project Example) — throws TerminalNotSupportedException immediately
• After exception — Ctrl+C works, cursor visible, echo on, alt screen exited

[Copilot]

Pull request overview

Adds startup safeguards to prevent SharpConsoleUI from hanging or leaving the user’s terminal in a broken state when run in non-interactive or non-ANSI-capable environments (Fixes #12).

Changes:

• Add Unix TTY detection (isatty) and throw TerminalNotSupportedException before entering raw/alt-screen when stdin/stdout are redirected.
• Add post-initialization DSR verification to confirm the terminal actually responds to ANSI escape sequences.
• Make shutdown more tolerant of partial initialization by guarding some post-restore Console.* calls.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
SharpConsoleUI/Helpers/TerminalCapabilities.cs	Adds DSR-based “terminal responds” verification helper.
SharpConsoleUI/Drivers/TerminalNotSupportedException.cs	Introduces a dedicated exception type for unsupported terminal environments.
SharpConsoleUI/Drivers/NetConsoleDriver.cs	Implements fail-fast TTY check, DSR verification, and partial-cleanup hardening; adds signal restore helper.
SharpConsoleUI/Drivers/Input/TerminalRawMode.cs	Adds isatty() P/Invoke and a helper to detect stdin/stdout TTY status.
SharpConsoleUI/Configuration/SystemDefaults.cs	Adds a default timeout constant for terminal verification.

Comments suppressed due to low confidence (1)

SharpConsoleUI/Drivers/NetConsoleDriver.cs:639

• Stop() now guards some Console.* calls, but it still calls SetCursorVisible(true) / ResetCursorShape() unguarded after Cleanup(). In partial-initialization scenarios where Console APIs are unavailable (or Console.Out was never restored), these can still throw and defeat the goal of making Stop() safe after a failed/partial Start(). Consider wrapping these calls in the same try/catch or making SetCursorVisible resilient to Console failures.

			Cleanup();

			try { Console.Clear(); } catch { }

			// Restore cursor visibility on shutdown
			SetCursorVisible(true);
			ResetCursorShape();
		}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The comment describing the effective worst-case timeout assumes ReadDSRColumn calls readByte “~8 times”, but the number of reads depends on how many digits are in row/col and can be higher; for the “no response at all” case it’s typically just 1 call (the ESC read timing out). Consider rewording this to avoid an inaccurate bound, or describe the timeout semantics more precisely (per-byte timeout, total varies with response length).

[Copilot]

Start() sets _useDirectAnsi = isUnix before the TTY fail-fast check. If stdin/stdout are not TTY and you throw, the driver instance remains in “direct ANSI” mode even though raw mode was never entered, which can cause later calls (e.g., Stop() in a finally) to run the Unix raw cleanup path unnecessarily. Consider moving _useDirectAnsi assignment until after the TTY check passes, or explicitly resetting _useDirectAnsi = false just before throwing.

[Copilot]

The PR description mentions restoring suppressed signals when Start() throws, but the only restoration currently happens in the non-TTY early-return path. Any other exception during Start() (including failures after raw mode/alt-screen activation) will still leave SIGINT/SIGTSTP suppressed and the ProcessExit handler registered. Consider wrapping the body of Start() in try/catch/finally to roll back terminal state and restore signals / unregister handlers on any failure.

[Copilot]

On DSR verification failure, Start() calls Stop() and then throws. Stop() does not restore SIGINT/SIGTSTP suppression, so after this exception Ctrl+C/Ctrl+Z may remain disabled for the rest of the process. If the intent is “restore signals when Start throws”, make sure this path also restores them (either in Stop() for Unix, or in a Start() exception handler).

Suggested change

	Stop();
	try
	{
	Stop();
	}
	finally
	{
	// Ensure Ctrl+C/Ctrl+Z behavior is restored even when Start() throws
	Console.TreatControlCAsInput = false;
	}

[Copilot]

RestoreUnixSignal resets the signal handler to SIG_DFL, which may not match the caller’s previous handler (and signal() returns the previous handler specifically so it can be restored). If the library is going to restore signals, consider capturing the prior handler when suppressing and restoring that exact value instead of always forcing SIG_DFL.

[Copilot]

The XML docs for VerifyTerminalResponds say it “returns false on timeout” and contrasts with Probe “which swallows failures”, but the implementation catches all exceptions and returns false for parse errors or other failures too. Please align the documentation with behavior (e.g., “timeout or invalid response / error”) or narrow the catch to only handle timeouts.

Suggested change

	/// Unlike <see cref="Probe"/> which swallows failures, this returns false
	/// on timeout — indicating the terminal is not processing escape sequences.
	/// </summary>
	/// <param name="write">Action to write escape sequences to the terminal.</param>
	/// <param name="readByte">Function to read a single byte with timeout. Returns -1 on timeout.</param>
	/// <returns>True if the terminal responded, false if it timed out.</returns>
	/// Unlike <see cref="Probe"/> which swallows failures via cached defaults,
	/// this surfaces problems by returning false on timeout or invalid/error responses.
	/// </summary>
	/// <param name="write">Action to write escape sequences to the terminal.</param>
	/// <param name="readByte">
	/// Function to read a single byte with timeout. Returns -1 on timeout; may throw on error.
	/// </param>
	/// <returns>
	/// True if a valid DSR response was received and parsed; false if the read timed out,
	/// the response was invalid, or an error occurred while reading/parsing.
	/// </returns>