metaxy 0.0.0__py3-none-any.whl

metaxy/cli/graph_diff.py

@@ -0,0 +1,290 @@
+"""Graph diff commands for Metaxy CLI."""
+
+from typing import Annotated, Literal
+
+import cyclopts
+from rich.console import Console
+
+from metaxy.graph import RenderConfig
+
+# Rich console for formatted output
+console = Console()
+
+# Graph-diff subcommand app
+app = cyclopts.App(
+    name="graph-diff",  # pyrefly: ignore[unexpected-keyword]
+    help="Compare and visualize graph snapshots",  # pyrefly: ignore[unexpected-keyword]
+    console=console,  # pyrefly: ignore[unexpected-keyword]
+)
+
+
+@app.command()
+def render(
+    from_snapshot: Annotated[
+        str,
+        cyclopts.Parameter(
+            help='First snapshot to compare (can be "latest", "current", or snapshot hash)',
+        ),
+    ],
+    to_snapshot: Annotated[
+        str,
+        cyclopts.Parameter(
+            help='Second snapshot to compare (can be "latest", "current", or snapshot hash)',
+        ),
+    ] = "current",
+    store: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--store"],
+            help="Metadata store to use (defaults to configured default store)",
+        ),
+    ] = None,
+    format: Annotated[
+        Literal["terminal", "cards", "mermaid", "graphviz", "json", "yaml"],
+        cyclopts.Parameter(
+            name=["--format", "-f"],
+            help="Output format: terminal, cards, mermaid, graphviz, json, or yaml",
+        ),
+    ] = "terminal",
+    output: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--output", "-o"],
+            help="Output file path (default: stdout)",
+        ),
+    ] = None,
+    config: Annotated[
+        RenderConfig | None,
+        cyclopts.Parameter(name="*", help="Render configuration"),
+    ] = None,
+    # Preset modes
+    minimal: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--minimal"],
+            help="Minimal output: only feature keys and dependencies",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--verbose"],
+            help="Verbose output: show all available information",
+        ),
+    ] = False,
+):
+    """Render merged graph visualization comparing two snapshots.
+
+    Shows all features color-coded by status (added/removed/changed/unchanged).
+    Uses the unified rendering system - same renderers as 'metaxy graph render'.
+
+    Special snapshot literals:
+    - "latest": Most recent snapshot in the store
+    - "current": Current graph state from code
+
+    Output formats:
+    - terminal: Hierarchical tree view (default)
+    - cards: Panel/card-based view
+    - mermaid: Mermaid flowchart diagram
+    - graphviz: Graphviz DOT format
+
+    Examples:
+        # Show merged graph with default terminal renderer
+        $ metaxy graph-diff render latest current
+
+        # Cards view
+        $ metaxy graph-diff render latest current --format cards
+
+        # Focus on specific feature with 2 levels up and 1 level down
+        $ metaxy graph-diff render latest current --feature user/profile --up 2 --down 1
+
+        # Show only changed fields (hide unchanged)
+        $ metaxy graph-diff render latest current --show-changed-fields-only
+
+        # Save Mermaid diagram to file
+        $ metaxy graph-diff render latest current --format mermaid --output diff.mmd
+
+        # Graphviz DOT format
+        $ metaxy graph-diff render latest current --format graphviz --output diff.dot
+
+        # Minimal view
+        $ metaxy graph-diff render latest current --minimal
+
+        # Everything
+        $ metaxy graph-diff render latest current --verbose
+    """
+    from metaxy.cli.context import get_store
+    from metaxy.entrypoints import load_features
+    from metaxy.graph import (
+        CardsRenderer,
+        GraphData,
+        GraphvizRenderer,
+    )
+    from metaxy.graph.diff.differ import GraphDiffer, SnapshotResolver
+    from metaxy.models.feature import FeatureGraph
+
+    # Validate format
+    valid_formats = ["terminal", "cards", "mermaid", "graphviz", "json", "yaml"]
+    if format not in valid_formats:
+        console.print(
+            f"[red]Error:[/red] Invalid format '{format}'. Must be one of: {', '.join(valid_formats)}"
+        )
+        raise SystemExit(1)
+
+    # Resolve configuration from presets
+    if minimal and verbose:
+        console.print("[red]Error:[/red] Cannot specify both --minimal and --verbose")
+        raise SystemExit(1)
+
+    # If config is None, create a default instance
+    if config is None:
+        config = RenderConfig()
+
+    # Apply presets if specified (overrides display settings but preserves filtering)
+    if minimal:
+        preset = RenderConfig.minimal()
+        # Preserve filtering parameters from original config
+        preset.feature = config.feature
+        preset.up = config.up
+        preset.down = config.down
+        config = preset
+    elif verbose:
+        preset = RenderConfig.verbose()
+        # Preserve filtering parameters from original config
+        preset.feature = config.feature
+        preset.up = config.up
+        preset.down = config.down
+        config = preset
+
+    # Validate filtering options
+    if (config.up is not None or config.down is not None) and config.feature is None:
+        console.print(
+            "[red]Error:[/red] --up and --down require --feature to be specified"
+        )
+        raise SystemExit(1)
+
+    # Load features from entrypoints (needed for "current" literal)
+    load_features()
+    graph = FeatureGraph.get_active()
+
+    metadata_store = get_store(store)
+
+    with metadata_store:
+        # Resolve snapshot versions
+        resolver = SnapshotResolver()
+        try:
+            from_snapshot_version = resolver.resolve_snapshot(
+                from_snapshot, metadata_store, graph
+            )
+            to_snapshot_version = resolver.resolve_snapshot(
+                to_snapshot, metadata_store, graph
+            )
+        except ValueError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+
+        # Load snapshot data
+        differ = GraphDiffer()
+        try:
+            from_snapshot_data = differ.load_snapshot_data(
+                metadata_store, from_snapshot_version
+            )
+            to_snapshot_data = differ.load_snapshot_data(
+                metadata_store, to_snapshot_version
+            )
+        except ValueError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+
+        # Compute diff
+        graph_diff = differ.diff(from_snapshot_data, to_snapshot_data)
+
+        # Create merged graph data
+        merged_data = differ.create_merged_graph_data(
+            from_snapshot_data, to_snapshot_data, graph_diff
+        )
+
+        # Apply graph slicing if requested
+        if config.feature is not None:
+            try:
+                merged_data = differ.filter_merged_graph(
+                    merged_data,
+                    focus_feature=config.feature,
+                    up=config.up,
+                    down=config.down,
+                )
+            except ValueError as e:
+                console.print(f"[red]Error:[/red] {e}")
+                raise SystemExit(1)
+
+        # Render the diff
+        # Use DiffFormatter for terminal/json/yaml/mermaid (has proper diff visualization)
+        # Use unified renderers for cards/graphviz (DiffFormatter doesn't support these)
+        if format in ("terminal", "mermaid", "json", "yaml"):
+            from metaxy.graph.diff.rendering.formatter import DiffFormatter
+
+            formatter = DiffFormatter(console)
+
+            # Determine show_all_fields based on config
+            # TODO: add show_changed_fields_only to config
+            show_all_fields = True  # Default: show all fields
+
+            try:
+                rendered = formatter.format(
+                    merged_data=merged_data,
+                    format=format,
+                    verbose=verbose,
+                    diff_only=False,  # Always use merged view for graph-diff render
+                    show_all_fields=show_all_fields,
+                )
+            except Exception as e:
+                console.print(f"[red]Error:[/red] Rendering failed: {e}")
+                import traceback
+
+                traceback.print_exc()
+                raise SystemExit(1)
+        else:
+            # Use unified renderers for cards/graphviz formats
+            from metaxy.graph.diff.rendering.theme import Theme
+
+            theme = Theme.default()
+            graph_data = GraphData.from_merged_diff(merged_data)
+
+            if format == "cards":
+                renderer = CardsRenderer(
+                    graph_data=graph_data, config=config, theme=theme
+                )
+            elif format == "graphviz":
+                renderer = GraphvizRenderer(
+                    graph_data=graph_data, config=config, theme=theme
+                )
+            else:
+                console.print(f"[red]Error:[/red] Unknown format: {format}")
+                raise SystemExit(1)
+
+            try:
+                rendered = renderer.render()
+            except Exception as e:
+                console.print(f"[red]Error:[/red] Rendering failed: {e}")
+                import traceback
+
+                traceback.print_exc()
+                raise SystemExit(1)
+
+        # Output to file or stdout
+        if output:
+            try:
+                with open(output, "w") as f:
+                    f.write(rendered)
+                console.print(f"[green]Success:[/green] Diff rendered to: {output}")
+            except Exception as e:
+                console.print(f"[red]Error:[/red] Failed to write to file: {e}")
+                raise SystemExit(1)
+        else:
+            # Print to stdout
+            if format in ("terminal", "cards"):
+                # Use plain print for terminal formats (they have ANSI codes)
+                print(rendered)
+            else:
+                # Use Rich console for non-terminal formats
+                console.print(rendered)

metaxy/cli/list.py

@@ -0,0 +1,42 @@
+import cyclopts
+from rich.console import Console
+
+# Rich console for formatted output
+console = Console()
+
+# Migrations subcommand app
+app = cyclopts.App(
+    name="list",  # pyrefly: ignore[unexpected-keyword]
+    help="List Metaxy entities",  # pyrefly: ignore[unexpected-keyword]
+    console=console,  # pyrefly: ignore[unexpected-keyword]
+)
+
+
+@app.command()
+def features():
+    """List Metaxy features"""
+    from metaxy.cli.context import set_config
+    from metaxy.config import MetaxyConfig
+    from metaxy.entrypoints import load_features
+    from metaxy.models.plan import FQFieldKey
+
+    metaxy_config = MetaxyConfig.load(search_parents=True)
+
+    set_config(metaxy_config)
+
+    graph = load_features()
+
+    for feature_key, feature_spec in graph.feature_specs_by_key.items():
+        console.print("---")
+        console.print(
+            f"{feature_key} (version {graph.get_feature_version(feature_key)})"
+        )
+        if feature_spec.deps:
+            console.print("  Feature Dependencies:")
+            for dep in feature_spec.deps:
+                console.print(f"    {dep}")
+        console.print("  Fields:")
+        for field_key, field_spec in feature_spec.fields_by_key.items():
+            console.print(
+                f"    {field_spec.key.to_string()} (code_version {field_spec.code_version}, version {graph.get_field_version(FQFieldKey(feature=feature_key, field=field_key))})"
+            )

metaxy/cli/metadata.py

@@ -0,0 +1,271 @@
+"""Metadata management commands for Metaxy CLI."""
+
+from typing import TYPE_CHECKING, Annotated
+
+import cyclopts
+from rich.console import Console
+
+from metaxy.models.types import FeatureKey
+
+if TYPE_CHECKING:
+    from metaxy.models.feature import Feature
+
+# Rich console for formatted output
+console = Console()
+
+# Metadata subcommand app
+app = cyclopts.App(
+    name="metadata",  # pyrefly: ignore[unexpected-keyword]
+    help="Manage Metaxy metadata",  # pyrefly: ignore[unexpected-keyword]
+    console=console,  # pyrefly: ignore[unexpected-keyword]
+)
+
+
+@app.command()
+def copy(
+    from_store: Annotated[
+        str,
+        cyclopts.Parameter(
+            name=["--from", "FROM"],
+            help="Source store name (must be configured in metaxy.toml)",
+        ),
+    ],
+    to_store: Annotated[
+        str,
+        cyclopts.Parameter(
+            name=["--to", "TO"],
+            help="Destination store name (must be configured in metaxy.toml)",
+        ),
+    ],
+    features: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            name=["--feature"],
+            help="Feature key to copy (e.g., 'my_feature' or 'group/my_feature'). Can be repeated multiple times. If not specified, uses --all-features.",
+        ),
+    ] = None,
+    all_features: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--all-features"],
+            help="Copy all features from source store",
+        ),
+    ] = False,
+    from_snapshot: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--snapshot"],
+            help="Snapshot version to copy (defaults to latest in source store). The snapshot_version is preserved in the destination.",
+        ),
+    ] = None,
+    incremental: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--incremental"],
+            help="Use incremental copy (compare data_version to skip existing rows). Disable for better performance if destination is empty or uses deduplication.",
+        ),
+    ] = True,
+):
+    """Copy metadata between stores.
+
+    Copies metadata for specified features from one store to another,
+    optionally using a historical version. Useful for:
+    - Migrating data between environments
+    - Backfilling metadata
+    - Copying specific feature versions
+
+    Incremental Mode (default):
+        By default, performs an anti-join on sample_uid to skip rows that already exist
+        in the destination for the same snapshot_version. This prevents duplicate writes.
+
+        Disabling incremental (--no-incremental) may improve performance when:
+        - The destination store is empty or has no overlap with source
+        - The destination store has eventual deduplication
+
+    Examples:
+        # Copy all features from latest snapshot in dev to staging
+        $ metaxy metadata copy --from dev --to staging --all-features
+
+        # Copy specific features (repeatable flag)
+        $ metaxy metadata copy --from dev --to staging --feature user_features --feature customer_features
+
+        # Copy specific snapshot
+        $ metaxy metadata copy --from prod --to staging --all-features --snapshot abc123
+
+        # Non-incremental copy (faster, but may create duplicates)
+        $ metaxy metadata copy --from dev --to staging --all-features --no-incremental
+    """
+    import logging
+
+    from metaxy.cli.context import get_config
+
+    # Enable logging to show progress
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    config = get_config()
+
+    # Validate arguments
+    if not all_features and not features:
+        console.print(
+            "[red]Error:[/red] Must specify either --all-features or --feature"
+        )
+        raise SystemExit(1)
+
+    if all_features and features:
+        console.print(
+            "[red]Error:[/red] Cannot specify both --all-features and --feature"
+        )
+        raise SystemExit(1)
+
+    # Parse feature keys
+    feature_keys: list[FeatureKey | type[Feature]] | None = None
+    if features:
+        feature_keys = []
+        for feature_str in features:
+            # Parse feature key (supports both "feature" and "part1/part2/..." formats)
+            if "/" in feature_str:
+                parts = feature_str.split("/")
+                feature_keys.append(FeatureKey(parts))
+            else:
+                # Single-part key
+                feature_keys.append(FeatureKey([feature_str]))
+
+    # Get stores
+    console.print(f"[cyan]Source store:[/cyan] {from_store}")
+    console.print(f"[cyan]Destination store:[/cyan] {to_store}")
+
+    source_store = config.get_store(from_store)
+    dest_store = config.get_store(to_store)
+
+    # Open both stores and copy
+    with source_store, dest_store:
+        console.print("\n[bold]Starting copy operation...[/bold]\n")
+
+        try:
+            stats = dest_store.copy_metadata(
+                from_store=source_store,
+                features=feature_keys,
+                from_snapshot=from_snapshot,
+                incremental=incremental,
+            )
+
+            console.print(
+                f"\n[green]✓[/green] Copy complete: {stats['features_copied']} features, {stats['rows_copied']} rows"
+            )
+
+        except Exception as e:
+            console.print(f"\n[red]✗[/red] Copy failed:\n{e}")
+            raise SystemExit(1)
+
+
+@app.command()
+def drop(
+    store: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--store"],
+            help="Store name to drop metadata from (defaults to configured default store)",
+        ),
+    ] = None,
+    features: Annotated[
+        list[str] | None,
+        cyclopts.Parameter(
+            name=["--feature"],
+            help="Feature key to drop (e.g., 'my_feature' or 'group/my_feature'). Can be repeated multiple times. If not specified, uses --all-features.",
+        ),
+    ] = None,
+    all_features: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--all-features"],
+            help="Drop metadata for all features in the store",
+        ),
+    ] = False,
+    confirm: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--confirm"],
+            help="Confirm the drop operation (required to prevent accidental deletion)",
+        ),
+    ] = False,
+):
+    """Drop metadata from a store.
+
+    Removes metadata for specified features from the store.
+    This is a destructive operation and requires --confirm flag.
+
+    Useful for:
+    - Cleaning up test data
+    - Re-computing feature metadata from scratch
+    - Removing obsolete features
+
+    Examples:
+        # Drop specific feature (requires confirmation)
+        $ metaxy metadata drop --feature user_features --confirm
+
+        # Drop multiple features
+        $ metaxy metadata drop --feature user_features --feature customer_features --confirm
+
+        # Drop all features from specific store
+        $ metaxy metadata drop --store dev --all-features --confirm
+    """
+    from metaxy.cli.context import get_store
+
+    # Validate arguments
+    if not all_features and not features:
+        console.print(
+            "[red]Error:[/red] Must specify either --all-features or --feature"
+        )
+        raise SystemExit(1)
+
+    if all_features and features:
+        console.print(
+            "[red]Error:[/red] Cannot specify both --all-features and --feature"
+        )
+        raise SystemExit(1)
+
+    if not confirm:
+        console.print(
+            "[red]Error:[/red] This is a destructive operation. Must specify --confirm flag."
+        )
+        raise SystemExit(1)
+
+    # Parse feature keys
+    feature_keys: list[FeatureKey] = []
+    if features:
+        for feature_str in features:
+            # Parse feature key (supports both "feature" and "part1/part2/..." formats)
+            if "/" in feature_str:
+                parts = feature_str.split("/")
+                feature_keys.append(FeatureKey(parts))
+            else:
+                # Single-part key
+                feature_keys.append(FeatureKey([feature_str]))
+
+    # Get store
+    metadata_store = get_store(store)
+
+    with metadata_store:
+        # If all_features, get all feature keys from store
+        if all_features:
+            # Get all features that have metadata in the store
+            feature_keys = metadata_store.list_features(include_fallback=False)
+
+        console.print(
+            f"\n[bold]Dropping metadata for {len(feature_keys)} feature(s)...[/bold]\n"
+        )
+
+        dropped_count = 0
+        for feature_key in feature_keys:
+            try:
+                metadata_store.drop_feature_metadata(feature_key)
+                console.print(f"[green]✓[/green] Dropped: {feature_key.to_string()}")
+                dropped_count += 1
+            except Exception as e:
+                console.print(
+                    f"[red]✗[/red] Failed to drop {feature_key.to_string()}: {e}"
+                )
+
+        console.print(
+            f"\n[green]✓[/green] Drop complete: {dropped_count} feature(s) dropped"
+        )