mongrove 0.1.0__py3-none-any.whl

mongrove/__init__.py

@@ -0,0 +1,3 @@
+"""Mongrove package."""
+
+__version__ = "0.1.0"

mongrove/__main__.py

@@ -0,0 +1,7 @@
+"""Run Mongrove with ``python -m mongrove``."""
+
+from mongrove.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mongrove/cli.py

@@ -0,0 +1,217 @@
+"""Command-line entry point for Mongrove."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from mongrove import __version__
+from mongrove.domain.session import normalize_environment
+from mongrove.ui.app import MongroveApp
+from mongrove.ui.themes import CURATED_THEME_NAMES
+
+
+@dataclass(frozen=True, slots=True)
+class StartupOptions:
+    """Resolved startup settings after applying CLI-over-environment precedence."""
+
+    uri: str | None
+    profile: str | None
+    database: str | None
+    collection: str | None
+    read_only: bool
+    no_history: bool
+    config_dir: Path | None
+    theme: str | None
+    environment: str | None
+    allow_production_writes: bool
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser without starting a terminal UI."""
+
+    parser = argparse.ArgumentParser(
+        prog="mongrove",
+        description="A keyboard-first MongoDB workspace for the terminal.",
+    )
+    parser.add_argument(
+        "uri",
+        nargs="?",
+        help="MongoDB connection URI. Avoid passwords here when possible.",
+    )
+    parser.add_argument(
+        "--profile",
+        "--alias",
+        dest="profile",
+        help="Saved connection alias to preselect.",
+    )
+    parser.add_argument("--database", help="Database to open after connecting.")
+    parser.add_argument("--collection", help="Collection to open after connecting.")
+    parser.add_argument(
+        "--read-only",
+        action="store_true",
+        default=None,
+        help="Hide write controls. MongoDB roles remain the security boundary.",
+    )
+    parser.add_argument(
+        "--no-history",
+        action="store_true",
+        default=None,
+        help="Disable local query history for this session.",
+    )
+    parser.add_argument(
+        "--config-dir",
+        type=Path,
+        help="Override the directory containing local Mongrove configuration.",
+    )
+    parser.add_argument(
+        "--theme",
+        choices=CURATED_THEME_NAMES,
+        metavar="THEME",
+        help="Use a curated theme for this launch.",
+    )
+    parser.add_argument(
+        "--environment",
+        type=_parse_environment,
+        metavar="ENV",
+        help="Label this direct connection as development, staging, or production.",
+    )
+    parser.add_argument(
+        "--allow-production-writes",
+        action="store_true",
+        default=None,
+        help="Allow writes for a production target; each mutation still confirms explicitly.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Parse arguments and run the interactive application."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        options = resolve_startup_options(args)
+    except ValueError as error:
+        parser.error(str(error))
+    app = MongroveApp(
+        startup_uri=options.uri,
+        startup_profile=options.profile,
+        startup_database=options.database,
+        startup_collection=options.collection,
+        read_only=options.read_only,
+        no_history=options.no_history,
+        config_dir=options.config_dir,
+        theme_name=options.theme,
+        environment=options.environment,
+        allow_production_writes=options.allow_production_writes,
+    )
+    app.run()
+    return 0
+
+
+def resolve_startup_options(
+    args: argparse.Namespace,
+    environ: Mapping[str, str] | None = None,
+) -> StartupOptions:
+    """Resolve startup values with explicit command-line values taking priority.
+
+    A direct URI or alias supplied on the command line takes precedence over all
+    environment connection selectors. This prevents a shell's stale URI from
+    silently changing an explicitly requested target.
+    """
+
+    environment = os.environ if environ is None else environ
+    if args.uri:
+        uri = args.uri
+        profile = None
+    elif args.profile:
+        uri = None
+        profile = args.profile
+    else:
+        uri = _environment_value(environment, "MONGROVE_URI")
+        profile = None if uri else _environment_value(environment, "MONGROVE_PROFILE")
+
+    resolved_environment = (
+        args.environment
+        if args.environment is not None
+        else normalize_environment(_environment_value(environment, "MONGROVE_ENVIRONMENT"))
+    )
+    theme = args.theme or _environment_value(environment, "MONGROVE_THEME")
+    if theme is not None and theme not in CURATED_THEME_NAMES:
+        choices = ", ".join(CURATED_THEME_NAMES)
+        raise ValueError(f"MONGROVE_THEME must be one of: {choices}.")
+
+    config_dir = args.config_dir
+    if config_dir is None:
+        config_dir_value = _environment_value(environment, "MONGROVE_CONFIG_DIR")
+        config_dir = Path(config_dir_value) if config_dir_value else None
+
+    return StartupOptions(
+        uri=uri,
+        profile=profile,
+        database=args.database or _environment_value(environment, "MONGROVE_DATABASE"),
+        collection=args.collection or _environment_value(environment, "MONGROVE_COLLECTION"),
+        read_only=_resolve_boolean_option(
+            args.read_only,
+            environment,
+            "MONGROVE_READ_ONLY",
+        ),
+        no_history=_resolve_boolean_option(
+            args.no_history,
+            environment,
+            "MONGROVE_NO_HISTORY",
+        ),
+        config_dir=config_dir,
+        theme=theme,
+        environment=resolved_environment,
+        allow_production_writes=_resolve_boolean_option(
+            args.allow_production_writes,
+            environment,
+            "MONGROVE_ALLOW_PRODUCTION_WRITES",
+        ),
+    )
+
+
+def _parse_environment(value: str) -> str:
+    try:
+        parsed = normalize_environment(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from error
+    if parsed is None:
+        raise argparse.ArgumentTypeError("Environment cannot be empty.")
+    return parsed
+
+
+def _environment_value(environment: Mapping[str, str], name: str) -> str | None:
+    value = environment.get(name)
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def _resolve_boolean_option(
+    command_line_value: bool | None,
+    environment: Mapping[str, str],
+    name: str,
+) -> bool:
+    if command_line_value is not None:
+        return command_line_value
+    value = _environment_value(environment, name)
+    if value is None:
+        return False
+    normalized = value.casefold()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    raise ValueError(f"{name} must be true or false.")

mongrove/domain/__init__.py

@@ -0,0 +1,30 @@
+"""Domain models and query parsing for Mongrove."""
+
+from mongrove.domain.connection import ConnectionInfo, ConnectionProfile
+from mongrove.domain.explain import ExplainFragment, ExplainResult, ExplainWarning
+from mongrove.domain.index import IndexInfo, IndexUsage, IndexUsageReport
+from mongrove.domain.pipeline import AggregationPipeline, PipelineValidationError, parse_pipeline
+from mongrove.domain.query import FindQuery, QueryFormState, QueryValidationError
+from mongrove.domain.session import SessionPolicy, normalize_environment
+from mongrove.domain.schema import SchemaField, SchemaReport
+
+__all__ = [
+    "AggregationPipeline",
+    "ConnectionInfo",
+    "ConnectionProfile",
+    "ExplainFragment",
+    "ExplainResult",
+    "ExplainWarning",
+    "FindQuery",
+    "IndexInfo",
+    "IndexUsage",
+    "IndexUsageReport",
+    "PipelineValidationError",
+    "QueryFormState",
+    "QueryValidationError",
+    "SessionPolicy",
+    "SchemaField",
+    "SchemaReport",
+    "normalize_environment",
+    "parse_pipeline",
+]

mongrove/domain/connection.py

@@ -0,0 +1,26 @@
+"""Connection-facing domain models for Mongrove."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionProfile:
+    """A locally saved connection endpoint without secret credentials."""
+
+    name: str
+    uri: str
+    favorite: bool = False
+    default_database: str | None = None
+    environment: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionInfo:
+    """Connection facts collected after a successful server ping."""
+
+    display_uri: str
+    server_version: str | None = None
+    topology: str | None = None
+    is_writable_primary: bool | None = None

mongrove/domain/explain.py

@@ -0,0 +1,208 @@
+"""Best-effort normalization of version-variable MongoDB explain responses."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from mongrove.domain.pipeline import AggregationPipeline
+from mongrove.domain.query import FindQuery
+
+
+@dataclass(frozen=True, slots=True)
+class ExplainFragment:
+    """One independently normalized planner fragment within an explain response."""
+
+    path: str
+    root_stage: str | None
+    stages: tuple[str, ...]
+    index_names: tuple[str, ...]
+    rejected_plan_count: int | None
+    optimized_pipeline: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ExplainWarning:
+    """Evidence-based planner observation, never an automatic tuning claim."""
+
+    code: str
+    severity: Literal["info", "warning"]
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class ExplainResult:
+    """Planner-only explain response with raw BSON-compatible fallback data."""
+
+    operation: Literal["find", "aggregation"]
+    elapsed_ms: int
+    fragments: tuple[ExplainFragment, ...]
+    warnings: tuple[ExplainWarning, ...]
+    raw: dict[str, Any]
+
+
+def normalize_find_explain(raw: dict[str, Any], query: FindQuery, elapsed_ms: int) -> ExplainResult:
+    """Normalize a planner-only find explain and retain the raw server response."""
+
+    result = _normalize("find", raw, elapsed_ms)
+    warnings = list(result.warnings)
+    if query.limit is None:
+        warnings.append(
+            ExplainWarning(
+                code="unbounded-find",
+                severity="info",
+                message="The logical find query has no limit.",
+            )
+        )
+    return ExplainResult(
+        operation=result.operation,
+        elapsed_ms=result.elapsed_ms,
+        fragments=result.fragments,
+        warnings=tuple(warnings),
+        raw=result.raw,
+    )
+
+
+def normalize_aggregation_explain(
+    raw: dict[str, Any],
+    pipeline: AggregationPipeline,
+    elapsed_ms: int,
+) -> ExplainResult:
+    """Normalize a planner-only aggregation explain and retain raw response data."""
+
+    return _normalize("aggregation", raw, elapsed_ms)
+
+
+def _normalize(
+    operation: Literal["find", "aggregation"],
+    raw: dict[str, Any],
+    elapsed_ms: int,
+) -> ExplainResult:
+    planners, truncated = _planner_nodes(raw)
+    fragments = tuple(_fragment(path, planner, raw) for path, planner in planners)
+    warnings: list[ExplainWarning] = []
+    stages = {stage for fragment in fragments for stage in fragment.stages}
+    if "COLLSCAN" in stages:
+        warnings.append(
+            ExplainWarning("collection-scan", "warning", "Observed COLLSCAN in the winning plan.")
+        )
+    if "SORT" in stages:
+        warnings.append(
+            ExplainWarning("in-memory-sort", "warning", "Observed SORT in the winning plan.")
+        )
+    if "SHARD_MERGE" in stages:
+        warnings.append(
+            ExplainWarning("shard-merge", "info", "Observed SHARD_MERGE in the winning plan.")
+        )
+    rejected = sum(fragment.rejected_plan_count or 0 for fragment in fragments)
+    if rejected:
+        warnings.append(
+            ExplainWarning(
+                "rejected-plans",
+                "info",
+                f"Observed {rejected} rejected planner candidate(s).",
+            )
+        )
+    if any(fragment.optimized_pipeline for fragment in fragments):
+        warnings.append(
+            ExplainWarning(
+                "optimized-pipeline",
+                "info",
+                "Server reported an optimized aggregation pipeline.",
+            )
+        )
+    if not fragments:
+        warnings.append(
+            ExplainWarning(
+                "unrecognized-shape",
+                "info",
+                "Plan shape was not normalized; inspect Raw EJSON for server-specific details.",
+            )
+        )
+    if truncated:
+        warnings.append(
+            ExplainWarning(
+                "normalization-truncated",
+                "info",
+                "Plan normalization reached its safety bound; inspect Raw EJSON for remaining details.",
+            )
+        )
+    return ExplainResult(
+        operation=operation,
+        elapsed_ms=elapsed_ms,
+        fragments=fragments,
+        warnings=tuple(warnings),
+        raw=raw,
+    )
+
+
+def _planner_nodes(raw: Mapping[str, Any]) -> tuple[list[tuple[str, Mapping[str, Any]]], bool]:
+    nodes: list[tuple[str, Mapping[str, Any]]] = []
+    truncated = False
+    visited = 0
+
+    def walk(value: Any, path: str, depth: int) -> None:
+        nonlocal truncated, visited
+        if depth > 24 or visited >= 1_000 or len(nodes) >= 32:
+            truncated = True
+            return
+        visited += 1
+        if isinstance(value, Mapping):
+            planner = value.get("queryPlanner")
+            if isinstance(planner, Mapping):
+                nodes.append((f"{path}.queryPlanner" if path else "queryPlanner", planner))
+            for key, child in value.items():
+                if key == "queryPlanner":
+                    continue
+                walk(child, f"{path}.{key}" if path else str(key), depth + 1)
+        elif isinstance(value, list):
+            for index, child in enumerate(value):
+                walk(child, f"{path}[{index}]", depth + 1)
+
+    walk(raw, "", 0)
+    return nodes, truncated
+
+
+def _fragment(path: str, planner: Mapping[str, Any], raw: Mapping[str, Any]) -> ExplainFragment:
+    winning = planner.get("winningPlan")
+    if not isinstance(winning, Mapping):
+        winning = {}
+    query_plan = winning.get("queryPlan")
+    root = query_plan if isinstance(query_plan, Mapping) else winning
+    stages, indexes = _plan_details(root)
+    rejected = planner.get("rejectedPlans")
+    return ExplainFragment(
+        path=path,
+        root_stage=stages[0] if stages else None,
+        stages=tuple(stages),
+        index_names=tuple(indexes),
+        rejected_plan_count=len(rejected) if isinstance(rejected, list) else None,
+        optimized_pipeline=bool(planner.get("optimizedPipeline") or raw.get("optimizedPipeline")),
+    )
+
+
+def _plan_details(root: Mapping[str, Any]) -> tuple[list[str], list[str]]:
+    stages: list[str] = []
+    indexes: list[str] = []
+    children = ("inputStage", "inputStages", "thenStage", "elseStage", "innerStage", "outerStage")
+
+    def walk(node: Any, depth: int) -> None:
+        if depth > 24 or not isinstance(node, Mapping):
+            return
+        stage = node.get("stage")
+        if isinstance(stage, str):
+            stages.append(stage)
+        index_name = node.get("indexName")
+        if isinstance(index_name, str) and index_name not in indexes:
+            indexes.append(index_name)
+        for key in children:
+            child = node.get(key)
+            if isinstance(child, list):
+                for item in child:
+                    walk(item, depth + 1)
+            else:
+                walk(child, depth + 1)
+
+    walk(root, 0)
+    return stages, indexes

mongrove/domain/index.py

@@ -0,0 +1,36 @@
+"""MongoDB index metadata models independent of PyMongo result objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class IndexInfo:
+    """One server-reported collection index and its complete raw specification."""
+
+    name: str
+    keys: tuple[tuple[str, Any], ...]
+    unique: bool
+    sparse: bool
+    hidden: bool
+    raw: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class IndexUsage:
+    """Best-effort node-local $indexStats usage data for one index."""
+
+    name: str
+    operations: int | None
+    since: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class IndexUsageReport:
+    """Usage availability is explicit so absent privileges never look like zero."""
+
+    available: bool
+    usages: tuple[IndexUsage, ...] = ()
+    message: str | None = None

mongrove/domain/namespace.py

@@ -0,0 +1,28 @@
+"""Models used by Mongrove namespace navigation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CollectionInfo:
+    """A collection or view returned by a MongoDB database."""
+
+    database: str
+    name: str
+    kind: str = "collection"
+
+    @property
+    def namespace(self) -> str:
+        return f"{self.database}.{self.name}"
+
+
+@dataclass(frozen=True, slots=True)
+class NamespaceTreeItem:
+    """Data attached to a Textual Tree node."""
+
+    kind: str
+    database: str
+    collection: str | None = None
+    collection_kind: str = "collection"

mongrove/domain/pipeline.py

@@ -0,0 +1,54 @@
+"""Validated BSON-aware aggregation pipeline models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from bson import json_util
+
+
+class PipelineValidationError(ValueError):
+    """Raised when raw editor text cannot become a MongoDB pipeline."""
+
+
+@dataclass(frozen=True, slots=True)
+class AggregationPipeline:
+    """Parsed pipeline plus a safety classification of its write stages."""
+
+    stages: tuple[dict[str, Any], ...]
+    write_stages: tuple[str, ...] = ()
+
+    @property
+    def has_write_stage(self) -> bool:
+        return bool(self.write_stages)
+
+
+def parse_pipeline(text: str) -> AggregationPipeline:
+    """Parse a JSON/EJSON array of one-key aggregation stage documents."""
+
+    if not text.strip():
+        raise PipelineValidationError("Pipeline cannot be empty; use [] for no stages.")
+    try:
+        parsed = json_util.loads(text)
+    except Exception as error:  # json_util exposes multiple parser exceptions.
+        raise PipelineValidationError(
+            f"Pipeline must be valid JSON or Extended JSON: {error}"
+        ) from error
+    if not isinstance(parsed, list):
+        raise PipelineValidationError("Pipeline must be a JSON array of stage documents.")
+
+    stages: list[dict[str, Any]] = []
+    write_stages: list[str] = []
+    for index, stage in enumerate(parsed, start=1):
+        if not isinstance(stage, dict) or len(stage) != 1:
+            raise PipelineValidationError(
+                f"Stage {index} must be a JSON document with exactly one operator."
+            )
+        operator = next(iter(stage))
+        if not isinstance(operator, str) or not operator.startswith("$"):
+            raise PipelineValidationError(f"Stage {index} must start with a $ operator.")
+        stages.append(stage)
+        if operator in {"$out", "$merge"}:
+            write_stages.append(operator)
+    return AggregationPipeline(tuple(stages), tuple(write_stages))