Auto-detect --format=strict when output is piped (#131)

Automatically detect when output is piped and use strict YAML format
instead of rich formatted output. This makes piping to tools like yq,
jq, or phabfive edit seamless without needing --format=strict flag.

Changes:
- Add _get_auto_format() method to Phabfive class that uses
  sys.stdout.isatty() to detect if output is a terminal or piped
- Update CLI to auto-detect format when --format not explicitly specified
- Update help text to document auto-detection behavior
- Add tests for auto-format detection (terminal vs piped)

Behavior:
- Terminal output: Uses 'rich' format (colored, formatted, hyperlinks)
- Piped output: Uses 'strict' format (pure YAML)
- Explicit --format=X: Overrides auto-detection

This aligns with existing --ascii=auto and --hyperlink=auto patterns
and follows industry standards from git, ripgrep, ls, etc.

Fixes #131

Author: holmboe

phabfive/cli.py

@@ -34,7 +34,9 @@
 
 Options:
     --log-level=LEVEL     Set loglevel [default: INFO]
-    --format=FORMAT       Output format: rich (default), tree, or strict [default: rich]
+    --format=FORMAT       Output format: rich, tree, or strict. Auto-detects based on TTY:
+                          terminal=rich (colored/formatted), piped=strict (pure YAML).
+                          Explicitly specify to override auto-detection.
     --ascii=WHEN          Use ASCII instead of Unicode (always/auto/never) [default: auto]
     --hyperlink=WHEN      Enable terminal hyperlinks (always/auto/never) [default: auto]
     -h, --help            Show this help message and exit
@@ -398,7 +400,14 @@ def run(cli_args, sub_args):
     # Validate and process output options
     valid_modes = ("always", "auto", "never")
     valid_formats = ("rich", "tree", "strict")
-    output_format = cli_args.get("--format", "rich")
+
+    # Auto-detect format based on TTY if not explicitly specified
+    format_arg = cli_args.get("--format")
+    if format_arg is None:
+        output_format = Phabfive._get_auto_format()
+    else:
+        output_format = format_arg
+
     ascii_when = cli_args.get("--ascii", "never")
     hyperlink_when = cli_args.get("--hyperlink", "never")
 

phabfive/core.py

@@ -128,6 +128,22 @@ def _should_use_hyperlink():
 
         return False
 
+    @staticmethod
+    def _get_auto_format():
+        """Determine default output format based on whether stdout is a TTY.
+
+        Returns:
+            str: "rich" if stdout is a terminal, "strict" if piped/redirected
+        """
+        import sys
+
+        # If output is piped or redirected, use strict format for machine processing
+        if not sys.stdout.isatty():
+            return "strict"
+
+        # If output is to a terminal, use rich format for human readability
+        return "rich"
+
     def _is_ascii_enabled(self):
         """Check if ASCII mode is currently enabled."""
         if self._ascii_when == "always":

tests/test_phabfive.py

@@ -1,5 +1,8 @@
 # -*- coding: utf-8 -*-
 
+# python std lib
+from unittest import mock
+
 # 3rd party imports
 import pytest
 
@@ -16,3 +19,23 @@ def test_import_phabfive():
         from phabfive.core import Phabfive  # noqa
     except ImportError:
         pytest.fail("Unexpected ImportError")
+
+
+class TestAutoFormatDetection:
+    """Tests for automatic format detection based on TTY status."""
+
+    def test_get_auto_format_terminal(self):
+        """Test auto-format returns 'rich' when stdout is a TTY."""
+        from phabfive.core import Phabfive
+
+        with mock.patch('sys.stdout.isatty', return_value=True):
+            result = Phabfive._get_auto_format()
+            assert result == "rich"
+
+    def test_get_auto_format_piped(self):
+        """Test auto-format returns 'strict' when stdout is piped/redirected."""
+        from phabfive.core import Phabfive
+
+        with mock.patch('sys.stdout.isatty', return_value=False):
+            result = Phabfive._get_auto_format()
+            assert result == "strict"