htmlgraph 0.26.24__py3-none-any.whl → 0.27.0__py3-none-any.whl

htmlgraph/builders/insight.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Insight builder for creating session insight nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with insight-specific methods for
 session health scoring and pattern detection.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 

htmlgraph/builders/metric.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Metric builder for creating aggregated metric nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with metric-specific methods for
 time-series aggregation and trend analysis.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any

htmlgraph/builders/pattern.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Pattern builder for creating workflow pattern nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with pattern-specific methods for
 tracking optimal and anti-pattern tool sequences.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any

htmlgraph/builders/phase.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Phase builder for creating project phase nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with phase-specific methods like
 phase ordering and dependencies.
 """
 
-from __future__ import annotations
 
 from datetime import date
 from typing import TYPE_CHECKING, Any

htmlgraph/builders/spike.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Spike builder for creating spike investigation nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with spike-specific methods like
 spike_type and timebox_hours.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 

htmlgraph/builders/track.py

@@ -1,8 +1,9 @@
+from __future__ import annotations
+
 """
 Track Builder for agent-friendly track creation.
 """
 
-from __future__ import annotations
 
 import re
 from datetime import datetime
@@ -617,6 +618,30 @@ class TrackBuilder:
                     Phase(id=f"phase-{i + 1}", name=phase_name, tasks=phase_tasks)
                 )
 
+        # Persist features to database from plan phases
+        features_created = 0
+        if phases:
+            for phase in phases:
+                for task in phase.tasks:
+                    # Generate feature ID from task description
+                    feature_id = generate_id(node_type="feat", title=task.description)
+
+                    # Insert feature into database
+                    success = self.sdk._db.insert_feature(
+                        feature_id=feature_id,
+                        feature_type="task",  # Tasks from tracks are features of type "task"
+                        title=task.description,
+                        status="todo",  # All new tasks start as "todo"
+                        priority=self._priority,  # Inherit priority from track
+                        assigned_to=None,  # No assignment initially
+                        track_id=track_id,
+                        description=f"Task from {phase.name}",
+                        steps_total=0,
+                        tags=None,
+                    )
+                    if success:
+                        features_created += 1
+
         if self._consolidated:
             # Single-file format: everything in one index.html
             track_file = self.sdk._directory / "tracks" / f"{track_id}.html"
@@ -677,6 +702,8 @@ class TrackBuilder:
         if self._plan_phases:
             total_tasks = sum(len(tasks) for _, tasks in self._plan_phases)
             print(f"  - Plan with {len(self._plan_phases)} phases, {total_tasks} tasks")
+        if features_created > 0:
+            print(f"  - Persisted {features_created} features to database")
 
         return track
 

htmlgraph/cli/analytics.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Analytics and reporting commands.
 
 Commands for analytics and reporting:
@@ -7,7 +9,6 @@ Commands for analytics and reporting:
 - sync-docs: Documentation synchronization
 """
 
-from __future__ import annotations
 
 import argparse
 import json

htmlgraph/cli/base.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """Base classes and utilities for CLI commands.
 
 Provides:
@@ -10,7 +12,6 @@ Provides:
 - save_traceback: Save full tracebacks to log files instead of console
 """
 
-from __future__ import annotations
 
 import argparse
 import json
@@ -464,11 +465,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 +497,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 +521,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 +558,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 +670,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/core.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Infrastructure commands.
 
 Commands for core infrastructure operations:
@@ -11,7 +13,6 @@ Commands for core infrastructure operations:
 - Other utilities
 """
 
-from __future__ import annotations
 
 import argparse
 import sys

htmlgraph/cli/main.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Main entry point.
 
 Entry point with argument parsing and command routing.
 Keeps main() thin by delegating to command modules.
 """
 
-from __future__ import annotations
 
 import argparse
 import sys

htmlgraph/cli/models.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Pydantic models for command filters and configuration.
 
 This module provides type-safe models for validating command inputs:
@@ -5,7 +7,6 @@ This module provides type-safe models for validating command inputs:
 - Configuration models for infrastructure commands (init, serve)
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import Literal

htmlgraph/cli/templates/cost_dashboard.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """HTML template for cost dashboard.
 
 This module generates a beautiful, interactive HTML dashboard for cost analysis.
 Separated from main CLI code for maintainability and testability.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any

htmlgraph/cli/work/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Work management commands.
 
 Commands for managing work items:
@@ -9,7 +11,6 @@ Commands for managing work items:
 - Other work-related operations
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
@@ -23,6 +24,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 +33,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 +45,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 +141,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 +160,10 @@ __all__ = [
     "SessionStartInfoCommand",
     # Report commands
     "SessionReportCommand",
+    # Snapshot commands
+    "SnapshotCommand",
+    # Browse commands
+    "BrowseCommand",
     # Feature commands
     "FeatureListCommand",
     "FeatureCreateCommand",

htmlgraph/cli/work/browse.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+"""HtmlGraph CLI - Browse command for opening dashboard in browser."""
+
+
+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,
+        )

htmlgraph/cli/work/features.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Feature management commands."""
 
-from __future__ import annotations
 
 import argparse
 from typing import TYPE_CHECKING

htmlgraph/cli/work/orchestration.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Orchestration commands (Archive, Orchestrator, Claude)."""
 
-from __future__ import annotations
 
 import argparse
 from datetime import datetime

htmlgraph/cli/work/report.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Session report commands.
 
 Commands for generating "What Did Claude Do?" reports:
@@ -7,7 +9,6 @@ THE killer feature that differentiates HtmlGraph - complete observability
 of AI agent activities with cost attribution and tool usage analysis.
 """
 
-from __future__ import annotations
 
 import argparse
 import sqlite3

htmlgraph/cli/work/sessions.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Session management commands."""
 
-from __future__ import annotations
 
 import argparse
 from typing import TYPE_CHECKING