Skip to content

Commit 4ba12e0

Browse files
djm81djm81
committed
Merge branch 'dev' into main (v0.22.1)
- Terminal output auto-detection and adaptive formatting - Bridge probe priority fix (layout-specific adapters before generic) - All conflicts resolved using dev branch changes - Version updated to 0.22.1
2 parents ec2697b + d8662ef commit 4ba12e0

25 files changed

+1290
-71
lines changed

‎CHANGELOG.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,87 @@ All notable changes to this project will be documented in this file.
99

1010
---
1111

12+
## [0.22.1] - 2026-01-03
13+
14+
### Added (0.22.1)
15+
16+
- **Terminal Output Auto-Detection**: Automatic terminal capability detection and adaptive output formatting
17+
- **Terminal Capability Detection**: New `TerminalCapabilities` dataclass and `detect_terminal_capabilities()` function in `src/specfact_cli/utils/terminal.py`
18+
- **Terminal Mode Detection**: Three terminal modes (GRAPHICAL, BASIC, MINIMAL) automatically selected based on environment
19+
- **Rich Console Configuration**: `get_configured_console()` function provides Rich Console instances configured for detected terminal capabilities
20+
- **Progress Configuration**: `get_progress_config()` function provides appropriate Progress column configurations based on terminal mode
21+
- **Environment Variable Support**: Respects standard environment variables (`NO_COLOR`, `FORCE_COLOR`, `CI`, `TEST_MODE`, `PYTEST_CURRENT_TEST`)
22+
- **CI/CD Detection**: Automatically detects CI/CD environments (GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins, Buildkite) and uses BASIC mode
23+
- **Embedded Terminal Support**: Automatically detects embedded terminals (Cursor, VS Code) and adapts output for optimal readability
24+
- **TTY Detection**: Uses `sys.stdout.isatty()` to determine interactive vs non-interactive terminals
25+
- **Plain Text Progress**: `print_progress()` helper function for plain text progress updates in BASIC/MINIMAL modes
26+
- **Cached Console Instances**: Console instances are cached for performance (lazy initialization pattern)
27+
28+
- **Terminal Output Testing Guide**: New comprehensive testing guide `docs/guides/testing-terminal-output.md`
29+
- **Multiple Testing Methods**: Instructions for testing with `NO_COLOR`, `CI=true`, `TERM=dumb`, and other methods
30+
- **GNOME Terminal Instructions**: Specific instructions for Ubuntu/GNOME systems
31+
- **Verification Commands**: Commands to verify terminal mode detection and capabilities
32+
- **Expected Behavior**: Clear documentation of what to expect in each terminal mode
33+
34+
### Changed (0.22.1)
35+
36+
- **CLI Commands Terminal Output**: All CLI commands now use adaptive terminal output
37+
- **Import Command**: `specfact import` uses `get_configured_console()` and `get_progress_config()` for adaptive progress display
38+
- **Sync Command**: `specfact sync` uses adaptive terminal output for all progress indicators
39+
- **Generate Command**: `specfact generate` uses configured console for consistent output
40+
- **SDD Command**: `specfact sdd` uses adaptive terminal output
41+
- **Bridge Sync**: Internal `BridgeSync` class uses adaptive terminal output for progress indicators
42+
- **Progress Utilities**: `load_bundle_with_progress()` and `save_bundle_with_progress()` use lazy imports to avoid circular dependencies
43+
44+
- **Runtime Terminal Management**: Enhanced `src/specfact_cli/runtime.py` with terminal mode management
45+
- **TerminalMode Enum**: New enum with GRAPHICAL, BASIC, and MINIMAL values
46+
- **get_terminal_mode()**: Function to determine current terminal mode based on capabilities
47+
- **get_configured_console()**: Central function to get cached, configured Rich Console instance
48+
- **Integration**: All terminal detection logic integrated into runtime module
49+
50+
- **Documentation Updates**: Comprehensive documentation updates for terminal output behavior
51+
- **Troubleshooting Guide**: Added detailed "Terminal Output Issues" section in `docs/guides/troubleshooting.md`
52+
- Auto-detection explanation (detection order and logic)
53+
- Terminal modes documentation (GRAPHICAL, BASIC, MINIMAL)
54+
- Environment variable overrides
55+
- Examples and troubleshooting for embedded terminals and CI/CD
56+
- **UX Features Guide**: Updated "Unified Progress Display" section in `docs/guides/ux-features.md`
57+
- Added "Automatic Terminal Adaptation" subsection
58+
- Explains auto-detection for different terminal types
59+
- Links to troubleshooting guide
60+
- **IDE Integration Guide**: Added terminal output note in `docs/guides/ide-integration.md`
61+
- Mentions automatic detection for embedded terminals
62+
- Links to troubleshooting guide
63+
- **Use Cases Guide**: Added terminal output note in CI/CD use case section
64+
- Explains plain text output in CI/CD environments
65+
- Links to troubleshooting guide
66+
67+
### Fixed (0.22.1)
68+
69+
- **Circular Import Resolution**: Fixed circular dependency between `progress.py` and `runtime.py` using lazy imports
70+
- **Progress API Usage**: Fixed `Progress` initialization to use positional arguments for columns (not `columns` keyword)
71+
- **Console Configuration**: Fixed console configuration to properly respect terminal capabilities
72+
- **Test Environment**: Fixed test environment setup to properly simulate different terminal modes
73+
74+
### Documentation (0.22.1)
75+
76+
- **Terminal Output Documentation**: Comprehensive documentation for terminal output auto-detection
77+
- **Troubleshooting Section**: Complete terminal output troubleshooting guide with auto-detection details
78+
- **Testing Guide**: New guide for testing terminal output modes on different systems
79+
- **UX Features**: Updated progress display documentation with terminal adaptation details
80+
- **IDE Integration**: Added terminal output information for embedded terminals
81+
- **Use Cases**: Added CI/CD terminal output behavior documentation
82+
83+
### Notes (0.22.1)
84+
85+
- **Zero Configuration**: Terminal output auto-detection requires no manual configuration - works out of the box
86+
- **Backward Compatible**: All existing Rich features continue to work - auto-detection only enhances compatibility
87+
- **Standard Compliance**: Respects `NO_COLOR` standard (<https://no-color.org/>) for color disabling
88+
- **CI/CD Optimized**: Automatically uses plain text output in CI/CD for better log readability
89+
- **Test Mode Support**: Automatically uses minimal output when `TEST_MODE=true` or `PYTEST_CURRENT_TEST` is set
90+
91+
---
92+
1293
## [0.22.0] - 2026-01-01
1394

1495
### Breaking Changes (0.22.0)

‎docs/guides/ide-integration.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ permalink: /ide-integration/
1111

1212
**CLI-First Approach**: SpecFact works offline, requires no account, and integrates with your existing workflow. Works with VS Code, Cursor, GitHub Actions, pre-commit hooks, or any IDE. No platform to learn, no vendor lock-in.
1313

14+
**Terminal Output**: The CLI automatically detects embedded terminals (Cursor, VS Code) and CI/CD environments, adapting output formatting automatically. Progress indicators work in all environments - see [Troubleshooting](troubleshooting.md#terminal-output-issues) for details.
15+
1416
---
1517

1618
## Overview
@@ -320,6 +322,7 @@ The `specfact init` command handles all conversions automatically.
320322
- [Command Reference](../reference/commands.md) - All CLI commands
321323
- [CoPilot Mode Guide](copilot-mode.md) - Using `--mode copilot` on CLI
322324
- [Getting Started](../getting-started/installation.md) - Installation and setup
325+
- [Troubleshooting](troubleshooting.md#terminal-output-issues) - Terminal output auto-detection in embedded terminals
323326

324327
---
325328

‎docs/guides/testing-terminal-output.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
layout: default
3+
title: Testing Terminal Output Modes
4+
permalink: /testing-terminal-output/
5+
---
6+
7+
# Testing Terminal Output Modes
8+
9+
This guide explains how to test SpecFact CLI's terminal output auto-detection on Ubuntu/GNOME systems.
10+
11+
## Quick Test Methods
12+
13+
### Method 1: Use NO_COLOR (Easiest)
14+
15+
The `NO_COLOR` environment variable is the standard way to disable colors:
16+
17+
```bash
18+
# Test in current terminal session
19+
NO_COLOR=1 specfact --help
20+
21+
# Or export for the entire session
22+
export NO_COLOR=1
23+
specfact import from-code my-bundle
24+
unset NO_COLOR # Re-enable colors
25+
```
26+
27+
### Method 2: Simulate CI/CD Environment
28+
29+
Simulate a CI/CD pipeline (BASIC mode):
30+
31+
```bash
32+
# Set CI environment variable
33+
CI=true specfact --help
34+
35+
# Or simulate GitHub Actions
36+
GITHUB_ACTIONS=true specfact import from-code my-bundle
37+
```
38+
39+
### Method 3: Use Dumb Terminal Type
40+
41+
Force a "dumb" terminal that doesn't support colors:
42+
43+
```bash
44+
# Start a terminal with dumb TERM
45+
TERM=dumb specfact --help
46+
47+
# Or use vt100 (minimal terminal)
48+
TERM=vt100 specfact --help
49+
```
50+
51+
### Method 4: Redirect to Non-TTY
52+
53+
Redirect output to a file or pipe (non-interactive):
54+
55+
```bash
56+
# Redirect to file (non-TTY)
57+
specfact --help > output.txt 2>&1
58+
cat output.txt
59+
60+
# Pipe to another command (non-TTY)
61+
specfact --help | cat
62+
```
63+
64+
### Method 5: Use script Command
65+
66+
The `script` command can create a non-interactive session:
67+
68+
```bash
69+
# Create a script session (records to typescript file)
70+
script -c "specfact --help" output.txt
71+
72+
# Or use script with dumb terminal
73+
TERM=dumb script -c "specfact --help" output.txt
74+
```
75+
76+
## Testing in GNOME Terminal
77+
78+
### Option A: Launch Terminal with NO_COLOR
79+
80+
```bash
81+
# Launch gnome-terminal with NO_COLOR set
82+
gnome-terminal -- bash -c "export NO_COLOR=1; specfact --help; exec bash"
83+
```
84+
85+
### Option B: Create a Test Script
86+
87+
Create a test script `test-no-color.sh`:
88+
89+
```bash
90+
#!/bin/bash
91+
export NO_COLOR=1
92+
specfact --help
93+
```
94+
95+
Then run:
96+
97+
```bash
98+
chmod +x test-no-color.sh
99+
./test-no-color.sh
100+
```
101+
102+
### Option C: Use Different Terminal Emulators
103+
104+
Install and test with different terminal emulators:
105+
106+
```bash
107+
# Install alternative terminals
108+
sudo apt install xterm terminator
109+
110+
# Test with xterm (can be configured for minimal support)
111+
xterm -e "NO_COLOR=1 specfact --help"
112+
113+
# Test with terminator
114+
terminator -e "NO_COLOR=1 specfact --help"
115+
```
116+
117+
## Verifying Terminal Mode Detection
118+
119+
You can verify which mode is detected:
120+
121+
```bash
122+
# Check detected terminal mode
123+
python3 -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
124+
125+
# Check terminal capabilities
126+
python3 -c "
127+
from specfact_cli.utils.terminal import detect_terminal_capabilities
128+
caps = detect_terminal_capabilities()
129+
print(f'Color: {caps.supports_color}')
130+
print(f'Animations: {caps.supports_animations}')
131+
print(f'Interactive: {caps.is_interactive}')
132+
print(f'CI: {caps.is_ci}')
133+
"
134+
```
135+
136+
## Expected Behavior
137+
138+
### GRAPHICAL Mode (Default in Full Terminal)
139+
140+
- ✅ Colors enabled
141+
- ✅ Animations enabled
142+
- ✅ Full progress bars
143+
- ✅ Rich formatting
144+
145+
### BASIC Mode (NO_COLOR or CI/CD)
146+
147+
- ❌ No colors
148+
- ❌ No animations
149+
- ✅ Plain text progress updates
150+
- ✅ Readable output
151+
152+
### MINIMAL Mode (TEST_MODE)
153+
154+
- ❌ No colors
155+
- ❌ No animations
156+
- ❌ Minimal output
157+
- ✅ Test-friendly
158+
159+
## Complete Test Workflow
160+
161+
```bash
162+
# 1. Test with colors (default)
163+
specfact --help
164+
165+
# 2. Test without colors (NO_COLOR)
166+
NO_COLOR=1 specfact --help
167+
168+
# 3. Test CI/CD mode
169+
CI=true specfact --help
170+
171+
# 4. Test minimal mode
172+
TEST_MODE=true specfact --help
173+
174+
# 5. Verify detection
175+
python3 -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
176+
```
177+
178+
## Troubleshooting
179+
180+
If terminal detection isn't working as expected:
181+
182+
1. **Check environment variables**:
183+
184+
```bash
185+
echo "NO_COLOR: $NO_COLOR"
186+
echo "FORCE_COLOR: $FORCE_COLOR"
187+
echo "TERM: $TERM"
188+
echo "CI: $CI"
189+
```
190+
191+
2. **Verify TTY status**:
192+
193+
```bash
194+
python3 -c "import sys; print('Is TTY:', sys.stdout.isatty())"
195+
```
196+
197+
3. **Check terminal capabilities**:
198+
199+
```bash
200+
python3 -c "
201+
from specfact_cli.utils.terminal import detect_terminal_capabilities
202+
import json
203+
caps = detect_terminal_capabilities()
204+
print(json.dumps({
205+
'supports_color': caps.supports_color,
206+
'supports_animations': caps.supports_animations,
207+
'is_interactive': caps.is_interactive,
208+
'is_ci': caps.is_ci
209+
}, indent=2))
210+
"
211+
```
212+
213+
## Related Documentation
214+
215+
- [Troubleshooting](troubleshooting.md#terminal-output-issues) - Terminal output issues and auto-detection
216+
- [UX Features](ux-features.md) - User experience features including terminal output

0 commit comments

Comments
 (0)