htmlgraph 0.26.23__py3-none-any.whl → 0.26.25__py3-none-any.whl

htmlgraph/cli/base.py

@@ -464,11 +464,22 @@ class Formatter(Protocol):
 
 
 def _serialize_json(value: Any) -> Any:
-    """Recursively serialize value to JSON-compatible types."""
+    """Recursively serialize value to JSON-compatible types.
+
+    Sanitizes strings to remove control characters (newlines, tabs) that
+    would break JSON validity when using json.dumps().
+    """
     if value is None:
         return None
     if isinstance(value, (datetime, date)):
         return value.isoformat()
+    if isinstance(value, str):
+        # Sanitize string: replace control characters with spaces
+        # This prevents newlines/tabs in JSON string values from breaking JSON validity
+        sanitized = value.replace("\n", " ").replace("\r", " ").replace("\t", " ")
+        # Collapse multiple spaces to single space
+        sanitized = " ".join(sanitized.split())
+        return sanitized
     if hasattr(value, "model_dump") and callable(getattr(value, "model_dump")):
         return _serialize_json(value.model_dump())
     if hasattr(value, "to_dict") and callable(getattr(value, "to_dict")):
@@ -485,7 +496,9 @@ class JsonFormatter:
 
     def output(self, result: CommandResult) -> None:
         payload = result.json_data if result.json_data is not None else result.data
-        _console.print(json.dumps(_serialize_json(payload), indent=2))
+        # Use sys.stdout.write instead of _console.print to avoid Rich's line-wrapping
+        # which inserts literal newlines into JSON string values, breaking JSON validity
+        sys.stdout.write(json.dumps(_serialize_json(payload), indent=2) + "\n")
 
 
 class TextFormatter:
@@ -507,16 +520,21 @@ class TextFormatter:
                 _console.print(result.data)
             return
         if isinstance(result.text, str):
-            _console.print(result.text)
+            # Use sys.stdout.write() for ANSI-formatted text to preserve colors when piped
+            # This bypasses Rich's reprocessing and ensures ANSI codes are preserved
+            sys.stdout.write(result.text)
+            if not result.text.endswith("\n"):
+                sys.stdout.write("\n")
             return
-        _console.print("\n".join(str(line) for line in result.text))
+        # For text as list/iterable, write directly to preserve ANSI codes
+        sys.stdout.write("\n".join(str(line) for line in result.text) + "\n")
 
 
 def get_formatter(format_name: str) -> Formatter:
-    """Get formatter by name (json, text, plain)."""
+    """Get formatter by name (json, text, plain, refs)."""
     if format_name == "json":
         return JsonFormatter()
-    if format_name in ("text", "plain", ""):
+    if format_name in ("text", "plain", "refs", ""):
         return TextFormatter()
     raise CommandError(f"Unknown output format '{format_name}'")
 
@@ -539,6 +557,9 @@ class BaseCommand(ABC):
         self.graph_dir: str | None = None
         self.agent: str | None = None
         self._sdk: SDK | None = None
+        self.override_output_format: str | None = (
+            None  # Allow commands to override formatter
+        )
 
     @classmethod
     @abstractmethod
@@ -648,7 +669,10 @@ class BaseCommand(ABC):
         try:
             self.validate()
             result = self.execute()
-            formatter = get_formatter(output_format)
+            # Allow commands to override output format
+            # (e.g., snapshot command's --output-format flag overrides global --format)
+            actual_format = self.override_output_format or output_format
+            formatter = get_formatter(actual_format)
             formatter.output(result)
         except CommandError as exc:
             error_console = Console(file=sys.stderr)

htmlgraph/cli/work/__init__.py

@@ -23,6 +23,7 @@ def register_commands(subparsers: _SubParsersAction) -> None:
     Args:
         subparsers: Subparser action from ArgumentParser.add_subparsers()
     """
+    from htmlgraph.cli.work.browse import BrowseCommand
     from htmlgraph.cli.work.features import register_feature_commands
     from htmlgraph.cli.work.orchestration import (
         register_archive_commands,
@@ -31,6 +32,7 @@ def register_commands(subparsers: _SubParsersAction) -> None:
     )
     from htmlgraph.cli.work.report import register_report_commands
     from htmlgraph.cli.work.sessions import register_session_commands
+    from htmlgraph.cli.work.snapshot import SnapshotCommand
     from htmlgraph.cli.work.tracks import register_track_commands
 
     # Register all command groups
@@ -42,8 +44,75 @@ def register_commands(subparsers: _SubParsersAction) -> None:
     register_claude_commands(subparsers)
     register_report_commands(subparsers)
 
+    # Snapshot command
+    snapshot_parser = subparsers.add_parser(
+        "snapshot",
+        help="Output current graph state with refs",
+    )
+    snapshot_parser.add_argument(
+        "--output-format",
+        choices=["refs", "json", "text"],
+        default="refs",
+        help="Output format (default: refs)",
+    )
+    snapshot_parser.add_argument(
+        "--type",
+        help="Filter by type (feature, track, bug, spike, chore, epic, all)",
+    )
+    snapshot_parser.add_argument(
+        "--status",
+        help="Filter by status (todo, in_progress, blocked, done, all)",
+    )
+    snapshot_parser.add_argument(
+        "--track",
+        help="Show only items in a specific track (by track ID or ref)",
+    )
+    snapshot_parser.add_argument(
+        "--active",
+        action="store_true",
+        help="Show only TODO/IN_PROGRESS items (filters out metadata spikes)",
+    )
+    snapshot_parser.add_argument(
+        "--blockers",
+        action="store_true",
+        help="Show only critical/blocked items",
+    )
+    snapshot_parser.add_argument(
+        "--summary",
+        action="store_true",
+        help="Show counts and progress summary instead of listing all items",
+    )
+    snapshot_parser.add_argument(
+        "--my-work",
+        action="store_true",
+        help="Show items assigned to current agent",
+    )
+    snapshot_parser.set_defaults(func=SnapshotCommand.from_args)
+
+    # Browse command
+    browse_parser = subparsers.add_parser(
+        "browse",
+        help="Open dashboard in browser",
+    )
+    browse_parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Server port (default: 8080)",
+    )
+    browse_parser.add_argument(
+        "--query-type",
+        help="Filter by type (feature, track, bug, spike, chore, epic)",
+    )
+    browse_parser.add_argument(
+        "--query-status",
+        help="Filter by status (todo, in_progress, blocked, done)",
+    )
+    browse_parser.set_defaults(func=BrowseCommand.from_args)
+
 
 # Re-export all command classes for backward compatibility
+from htmlgraph.cli.work.browse import BrowseCommand
 from htmlgraph.cli.work.features import (
     FeatureClaimCommand,
     FeatureCompleteCommand,
@@ -71,6 +140,7 @@ from htmlgraph.cli.work.sessions import (
     SessionStartCommand,
     SessionStartInfoCommand,
 )
+from htmlgraph.cli.work.snapshot import SnapshotCommand
 from htmlgraph.cli.work.tracks import (
     TrackDeleteCommand,
     TrackListCommand,
@@ -89,6 +159,10 @@ __all__ = [
     "SessionStartInfoCommand",
     # Report commands
     "SessionReportCommand",
+    # Snapshot commands
+    "SnapshotCommand",
+    # Browse commands
+    "BrowseCommand",
     # Feature commands
     "FeatureListCommand",
     "FeatureCreateCommand",

htmlgraph/cli/work/browse.py

@@ -0,0 +1,114 @@
+"""HtmlGraph CLI - Browse command for opening dashboard in browser."""
+
+from __future__ import annotations
+
+import argparse
+import webbrowser
+from typing import TYPE_CHECKING
+
+from htmlgraph.cli.base import BaseCommand, CommandResult
+
+if TYPE_CHECKING:
+    pass
+
+
+class BrowseCommand(BaseCommand):
+    """Open the HtmlGraph dashboard in your default browser.
+
+    Usage:
+        htmlgraph browse                      # Open dashboard
+        htmlgraph browse --port 8080          # Custom port
+        htmlgraph browse --query-type feature # Show only features
+        htmlgraph browse --query-status todo  # Show only todo items
+    """
+
+    def __init__(
+        self,
+        *,
+        port: int = 8080,
+        query_type: str | None = None,
+        query_status: str | None = None,
+    ) -> None:
+        """Initialize BrowseCommand.
+
+        Args:
+            port: Server port (default: 8080)
+            query_type: Filter by type (feature, track, bug, spike, chore, epic)
+            query_status: Filter by status (todo, in_progress, blocked, done)
+        """
+        super().__init__()
+        self.port = port
+        self.query_type = query_type
+        self.query_status = query_status
+
+    @classmethod
+    def from_args(cls, args: argparse.Namespace) -> BrowseCommand:
+        """Create BrowseCommand from argparse arguments.
+
+        Args:
+            args: Argparse namespace with command arguments
+
+        Returns:
+            BrowseCommand instance
+        """
+        return cls(
+            port=args.port,
+            query_type=args.query_type,
+            query_status=args.query_status,
+        )
+
+    def execute(self) -> CommandResult:
+        """Execute the browse command.
+
+        Opens the dashboard in the default browser with optional query parameters.
+
+        Returns:
+            CommandResult with success status and URL
+        """
+        # Build URL with query params
+        url = f"http://localhost:{self.port}"
+
+        params = []
+        if self.query_type:
+            params.append(f"type={self.query_type}")
+        if self.query_status:
+            params.append(f"status={self.query_status}")
+
+        if params:
+            url += "?" + "&".join(params)
+
+        # Check if server is running
+        try:
+            import requests  # type: ignore[import-untyped]
+
+            response = requests.head(f"http://localhost:{self.port}", timeout=1)
+            response.raise_for_status()
+        except ImportError:
+            # requests module not available - try to open anyway with a warning
+            webbrowser.open(url)
+            return CommandResult(
+                data={"url": url},
+                text=f"Opening dashboard at {url}\n(Note: Could not verify server is running - install 'requests' for server checks)",
+                exit_code=0,
+            )
+        except Exception:
+            # Server not running or not responding
+            return CommandResult(
+                text=f"Dashboard server not running on port {self.port}.\nStart with: htmlgraph serve --port {self.port}",
+                exit_code=1,
+            )
+
+        # Open browser
+        try:
+            webbrowser.open(url)
+        except Exception as e:
+            return CommandResult(
+                text=f"Failed to open browser: {e}\nYou can manually visit: {url}",
+                exit_code=1,
+            )
+
+        return CommandResult(
+            data={"url": url},
+            text=f"Opening dashboard at {url}",
+            exit_code=0,
+        )