feat: Terminal output auto-detection and adaptive formatting (v0.22.1)

[djm81]

Summary

This PR implements automatic terminal capability detection and adaptive output formatting for SpecFact CLI. The CLI now automatically detects terminal capabilities and adjusts output formatting for optimal user experience across different environments (full terminals, embedded terminals, CI/CD pipelines).

Changes

Added

• Terminal Output Auto-Detection: Automatic terminal capability detection with three modes (GRAPHICAL, BASIC, MINIMAL)
• Rich Console Configuration: get_configured_console() function provides Rich Console instances configured for detected terminal capabilities
• Progress Configuration: get_progress_config() function provides appropriate Progress column configurations based on terminal mode
• Environment Variable Support: Respects standard environment variables (NO_COLOR, FORCE_COLOR, CI, TEST_MODE, PYTEST_CURRENT_TEST)
• CI/CD Detection: Automatically detects CI/CD environments and uses BASIC mode
• Embedded Terminal Support: Automatically detects embedded terminals (Cursor, VS Code) and adapts output
• Terminal Output Testing Guide: New comprehensive testing guide docs/guides/testing-terminal-output.md

Changed

• CLI Commands: All CLI commands now use adaptive terminal output
• Runtime Terminal Management: Enhanced runtime.py with terminal mode management
• Documentation: Comprehensive documentation updates across multiple guides

Fixed

• Circular Import Resolution: Fixed circular dependency between progress.py and runtime.py using lazy imports
• Progress API Usage: Fixed Progress initialization to use positional arguments for columns
• Console Configuration: Fixed console configuration to properly respect terminal capabilities

Testing

• ✅ All unit tests pass (terminal detection, console config, progress config)
• ✅ All integration tests pass (command output in different terminal modes)
• ✅ All E2E tests pass (full workflow in different terminal modes)
• ✅ Code formatting, linting, and type checking pass
• ✅ Test coverage meets requirements (≥80%)

Documentation

• ✅ Troubleshooting guide updated with terminal output section
• ✅ UX Features guide updated with terminal adaptation
• ✅ IDE Integration guide updated with terminal output note
• ✅ Use Cases guide updated with CI/CD terminal output behavior
• ✅ Testing guide created for terminal output testing
• ✅ CHANGELOG.md updated with version 0.22.1 release notes

Version

• Version updated to 0.22.1 across all version files:
  • pyproject.toml
  • setup.py
  • src/__init__.py
  • src/specfact_cli/__init__.py

Related

• Implements OpenSpec change: enhance-cli-terminal-output
• All tasks in change plan completed (except manual testing checklist)

Notes

• Zero configuration required - works out of the box
• Backward compatible - all existing Rich features continue to work
• Standard compliant - respects NO_COLOR standard (https://no-color.org/)
• CI/CD optimized - automatically uses plain text output for better log readability

[github-actions]

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 34.33s
Checks: 4 total (3 passed) (1 skipped)