py-data-engine 0.1.0__py3-none-any.whl

data_engine/services/theme.py

@@ -0,0 +1,59 @@
+"""Shared theme resolution services."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from data_engine.platform.theme import (
+    DEFAULT_THEME,
+    THEMES,
+    ThemePalette,
+    resolve_theme_name,
+    system_theme_name,
+    theme_button_text,
+    toggle_theme_name,
+)
+
+
+class ThemeService:
+    """Thin injectable wrapper around shared theme state decisions."""
+
+    def __init__(
+        self,
+        *,
+        themes: Mapping[str, ThemePalette] = THEMES,
+        default_theme_name: str = DEFAULT_THEME,
+        resolve_theme_name_func: Callable[[str], str] = resolve_theme_name,
+        system_theme_name_func: Callable[[], str] = system_theme_name,
+        toggle_theme_name_func: Callable[[str], str] = toggle_theme_name,
+        theme_button_text_func: Callable[[str], str] = theme_button_text,
+    ) -> None:
+        self._themes = themes
+        self.default_theme_name = default_theme_name
+        self._resolve_theme_name = resolve_theme_name_func
+        self._system_theme_name = system_theme_name_func
+        self._toggle_theme_name = toggle_theme_name_func
+        self._theme_button_text = theme_button_text_func
+
+    def resolve_name(self, theme_name: str = DEFAULT_THEME) -> str:
+        """Resolve one explicit or system-bound theme name."""
+        return self._resolve_theme_name(theme_name)
+
+    def system_name(self) -> str:
+        """Return the host-system theme name."""
+        return self._system_theme_name()
+
+    def toggle_name(self, theme_name: str) -> str:
+        """Return the opposite theme name."""
+        return self._toggle_theme_name(theme_name)
+
+    def button_text(self, theme_name: str) -> str:
+        """Return the user-facing theme toggle text."""
+        return self._theme_button_text(theme_name)
+
+    def palette(self, theme_name: str = DEFAULT_THEME) -> ThemePalette:
+        """Return the resolved semantic palette."""
+        return self._themes[self.resolve_name(theme_name)]
+
+
+__all__ = ["ThemeService"]

data_engine/services/workspace_provisioning.py

@@ -0,0 +1,224 @@
+"""Workspace provisioning helpers shared by CLI and GUI surfaces."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from data_engine.platform.workspace_models import (
+    DATA_ENGINE_WORKSPACE_COLLECTION_ROOT_ENV_VAR,
+    WORKSPACE_FLOW_HELPERS_DIR_NAME,
+    WorkspacePaths,
+    validate_workspace_id,
+)
+
+
+def checkout_source_dir(app_root: Path) -> Path | None:
+    """Return the repo-local source directory when app_root points at a checkout."""
+    src_dir = app_root / "src"
+    return src_dir if src_dir.is_dir() else None
+
+
+def checkout_tests_dir(app_root: Path) -> Path | None:
+    """Return the repo-local tests directory when app_root points at a checkout."""
+    tests_dir = app_root / "tests"
+    return tests_dir if tests_dir.is_dir() else None
+
+
+def workspace_vscode_settings(
+    workspace_root: Path,
+    *,
+    app_root: Path,
+    interpreter_path: Path | None = None,
+) -> dict[str, object]:
+    """Return VS Code settings for one workspace root."""
+    del interpreter_path
+    workspace_id = validate_workspace_id(workspace_root.name)
+    terminal_env = {
+        "DATA_ENGINE_APP_ROOT": str(app_root),
+        "DATA_ENGINE_WORKSPACE_ROOT": str(workspace_root),
+        "DATA_ENGINE_WORKSPACE_ID": workspace_id,
+    }
+    settings: dict[str, object] = {
+        "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
+        "files.exclude": {".workspace_state": True},
+        "search.exclude": {".workspace_state": True},
+        "terminal.integrated.env.linux": terminal_env,
+        "terminal.integrated.env.osx": terminal_env,
+        "terminal.integrated.env.windows": terminal_env,
+    }
+    src_dir = checkout_source_dir(app_root)
+    if src_dir is not None:
+        settings["python.analysis.extraPaths"] = [str(src_dir)]
+    tests_dir = checkout_tests_dir(app_root)
+    if tests_dir is not None:
+        settings["python.testing.pytestEnabled"] = True
+        settings["python.testing.pytestArgs"] = [str(tests_dir)]
+    return settings
+
+
+def collection_vscode_settings(
+    collection_root: Path,
+    *,
+    app_root: Path,
+    interpreter_path: Path | None = None,
+) -> dict[str, object]:
+    """Return VS Code settings for one workspace collection root."""
+    del interpreter_path
+    terminal_env = {
+        "DATA_ENGINE_APP_ROOT": str(app_root),
+        DATA_ENGINE_WORKSPACE_COLLECTION_ROOT_ENV_VAR: str(collection_root),
+    }
+    settings: dict[str, object] = {
+        "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
+        "files.exclude": {"**/.workspace_state": True},
+        "search.exclude": {"**/.workspace_state": True},
+        "terminal.integrated.env.linux": terminal_env,
+        "terminal.integrated.env.osx": terminal_env,
+        "terminal.integrated.env.windows": terminal_env,
+    }
+    src_dir = checkout_source_dir(app_root)
+    if src_dir is not None:
+        settings["python.analysis.extraPaths"] = [str(src_dir)]
+    tests_dir = checkout_tests_dir(app_root)
+    if tests_dir is not None:
+        settings["python.testing.pytestEnabled"] = True
+        settings["python.testing.pytestArgs"] = [str(tests_dir)]
+    return settings
+
+
+def write_workspace_vscode_settings(
+    workspace_root: Path,
+    *,
+    app_root: Path,
+    interpreter_path: Path | None = None,
+    overwrite: bool = False,
+) -> Path | None:
+    """Write workspace-local VS Code settings unless an existing file should be preserved."""
+    settings_path = workspace_root / ".vscode" / "settings.json"
+    if settings_path.exists() and not overwrite:
+        return None
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(
+        json.dumps(
+            workspace_vscode_settings(
+                workspace_root,
+                app_root=app_root,
+                interpreter_path=interpreter_path,
+            ),
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    return settings_path
+
+
+def write_collection_vscode_settings(
+    collection_root: Path,
+    *,
+    app_root: Path,
+    interpreter_path: Path | None = None,
+    overwrite: bool = False,
+) -> Path | None:
+    """Write collection-root VS Code settings unless an existing file should be preserved."""
+    settings_path = collection_root / ".vscode" / "settings.json"
+    if settings_path.exists() and not overwrite:
+        return None
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings_path.write_text(
+        json.dumps(
+            collection_vscode_settings(
+                collection_root,
+                app_root=app_root,
+                interpreter_path=interpreter_path,
+            ),
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    return settings_path
+
+
+@dataclass(frozen=True)
+class WorkspaceProvisioningResult:
+    """Describe which workspace assets were created during provisioning."""
+
+    workspace_root: Path
+    created_paths: tuple[Path, ...]
+    preserved_paths: tuple[Path, ...]
+
+    @property
+    def created_anything(self) -> bool:
+        """Return whether provisioning created any new files or directories."""
+        return bool(self.created_paths)
+
+
+class WorkspaceProvisioningService:
+    """Own safe workspace-folder provisioning for operator surfaces."""
+
+    def provision_workspace(
+        self,
+        workspace_paths: WorkspacePaths,
+        *,
+        interpreter_path: Path | None = None,
+    ) -> WorkspaceProvisioningResult:
+        """Provision missing authored-workspace folders without overwriting existing content."""
+        created_paths: list[Path] = []
+        preserved_paths: list[Path] = []
+        workspace_root = workspace_paths.workspace_root
+        if workspace_root.exists() and not workspace_root.is_dir():
+            raise ValueError(f"Workspace path is not a directory: {workspace_root}")
+        if not workspace_root.exists():
+            workspace_root.mkdir(parents=True, exist_ok=True)
+            created_paths.append(workspace_root)
+        collection_settings_path = write_collection_vscode_settings(
+            workspace_paths.workspace_collection_root,
+            app_root=workspace_paths.app_root,
+            interpreter_path=interpreter_path,
+            overwrite=False,
+        )
+        if collection_settings_path is None:
+            preserved_paths.append(workspace_paths.workspace_collection_root / ".vscode" / "settings.json")
+        else:
+            created_paths.append(collection_settings_path)
+        for directory in (
+            workspace_paths.flow_modules_dir,
+            workspace_paths.flow_modules_dir / WORKSPACE_FLOW_HELPERS_DIR_NAME,
+            workspace_paths.config_dir,
+            workspace_paths.databases_dir,
+        ):
+            if directory.exists():
+                preserved_paths.append(directory)
+                continue
+            directory.mkdir(parents=True, exist_ok=True)
+            created_paths.append(directory)
+        settings_path = write_workspace_vscode_settings(
+            workspace_root,
+            app_root=workspace_paths.app_root,
+            interpreter_path=interpreter_path,
+            overwrite=False,
+        )
+        if settings_path is None:
+            preserved_paths.append(workspace_root / ".vscode" / "settings.json")
+        else:
+            created_paths.append(settings_path)
+        return WorkspaceProvisioningResult(
+            workspace_root=workspace_root,
+            created_paths=tuple(created_paths),
+            preserved_paths=tuple(preserved_paths),
+        )
+
+
+__all__ = [
+    "WorkspaceProvisioningResult",
+    "WorkspaceProvisioningService",
+    "collection_vscode_settings",
+    "checkout_source_dir",
+    "checkout_tests_dir",
+    "write_collection_vscode_settings",
+    "workspace_vscode_settings",
+    "write_workspace_vscode_settings",
+]

data_engine/services/workspaces.py

@@ -0,0 +1,74 @@
+"""Workspace path and discovery services."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from data_engine.platform.workspace_models import DiscoveredWorkspace, WorkspacePaths
+from data_engine.platform.workspace_policy import AppStatePolicy, RuntimeLayoutPolicy, WorkspaceDiscoveryPolicy
+
+
+class WorkspaceService:
+    """Own workspace discovery and path resolution through explicit collaborators."""
+
+    def __init__(
+        self,
+        *,
+        app_state_policy: AppStatePolicy | None = None,
+        discovery_policy: WorkspaceDiscoveryPolicy | None = None,
+        runtime_layout_policy: RuntimeLayoutPolicy | None = None,
+        discover_workspaces_func: Callable[..., tuple[DiscoveredWorkspace, ...]] | None = None,
+        resolve_workspace_paths_func: Callable[..., WorkspacePaths] | None = None,
+    ) -> None:
+        self._app_state_policy = app_state_policy or AppStatePolicy()
+        self._discovery_policy = discovery_policy or WorkspaceDiscoveryPolicy(app_state_policy=self._app_state_policy)
+        self._runtime_layout_policy = runtime_layout_policy or RuntimeLayoutPolicy(
+            app_state_policy=self._app_state_policy,
+            discovery_policy=self._discovery_policy,
+        )
+        self._discover_workspaces = discover_workspaces_func
+        self._resolve_workspace_paths = resolve_workspace_paths_func
+
+    def discover(
+        self,
+        *,
+        app_root: Path | None = None,
+        workspace_collection_root: Path | None = None,
+    ) -> tuple[DiscoveredWorkspace, ...]:
+        """Return discoverable workspaces for the current app and collection roots."""
+        if self._discover_workspaces is None:
+            return self._discovery_policy.discover(
+                app_root=app_root,
+                workspace_collection_root=workspace_collection_root,
+            )
+        return self._discover_workspaces(
+            app_root=app_root,
+            workspace_collection_root=workspace_collection_root,
+        )
+
+    def resolve_paths(
+        self,
+        *,
+        workspace_id: str | None = None,
+        workspace_root: Path | None = None,
+        data_root: Path | None = None,
+        workspace_collection_root: Path | None = None,
+    ) -> WorkspacePaths:
+        """Resolve one workspace path set with the current override-aware rules."""
+        if self._resolve_workspace_paths is None:
+            return self._runtime_layout_policy.resolve_paths(
+                workspace_id=workspace_id,
+                workspace_root=workspace_root,
+                data_root=data_root,
+                workspace_collection_root=workspace_collection_root,
+            )
+        return self._resolve_workspace_paths(
+            workspace_id=workspace_id,
+            workspace_root=workspace_root,
+            data_root=data_root,
+            workspace_collection_root=workspace_collection_root,
+        )
+
+
+__all__ = ["WorkspaceService"]

data_engine/ui/__init__.py

@@ -0,0 +1,3 @@
+"""Operator surface packages for Data Engine."""
+
+__all__ = ["gui", "tui"]

data_engine/ui/cli/__init__.py

@@ -0,0 +1,19 @@
+"""CLI surface package."""
+
+from data_engine.ui.cli.app import (
+    CliDependencies,
+    CliDependencyFactories,
+    build_default_cli_dependencies,
+    build_parser,
+    default_cli_dependency_factories,
+    main,
+)
+
+__all__ = [
+    "CliDependencies",
+    "CliDependencyFactories",
+    "build_default_cli_dependencies",
+    "build_parser",
+    "default_cli_dependency_factories",
+    "main",
+]

data_engine/ui/cli/app.py

@@ -0,0 +1,161 @@
+"""Operator-focused CLI surface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+from data_engine.authoring.model import FlowValidationError
+from data_engine.platform.workspace_models import (
+    DATA_ENGINE_APP_ROOT_ENV_VAR,
+    DATA_ENGINE_WORKSPACE_ROOT_ENV_VAR,
+    InvalidWorkspaceIdError,
+    machine_id_text,
+)
+from data_engine.ui.cli import commands_doctor as _commands_doctor
+from data_engine.ui.cli import commands_run as _commands_run
+from data_engine.ui.cli.commands_start import (
+    launch_desktop_ui as _launch_desktop_ui,
+    launch_terminal_ui as _launch_terminal_ui,
+    preferred_gui_python_executable as _preferred_gui_python_executable,
+    start_gui_subprocess as _start_gui_subprocess,
+    start_surface as _start_surface,
+)
+from data_engine.ui.cli.commands_workspace import (
+    create_command as _create_command,
+    workspace_vscode_settings as _workspace_vscode_settings,
+)
+from data_engine.ui.cli.dependencies import (
+    CliDependencies,
+    CliDependencyFactories,
+    build_default_cli_dependencies,
+    default_cli_dependency_factories,
+)
+from data_engine.ui.cli.parser import _HelpFormatter, build_parser
+
+
+def _default_cli_dependencies() -> CliDependencies:
+    return build_default_cli_dependencies()
+
+
+def main(argv: list[str] | None = None, *, dependencies: CliDependencies | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    dependencies = dependencies or _default_cli_dependencies()
+    _apply_environment(args)
+
+    try:
+        if args.command == "start":
+            return _start_surface(args.start_command)
+        if args.command == "create":
+            return _create_command(args, dependencies=dependencies)
+        if args.command == "run":
+            return _run_command(args, dependencies=dependencies)
+        if args.command == "doctor":
+            return _doctor_command(args, dependencies=dependencies)
+    except (FlowValidationError, InvalidWorkspaceIdError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        print("Stopped.", file=sys.stderr)
+        return 130
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+def _apply_environment(args: argparse.Namespace) -> None:
+    if args.app_root is not None:
+        os.environ[DATA_ENGINE_APP_ROOT_ENV_VAR] = str(args.app_root.expanduser().resolve())
+    else:
+        inferred = _infer_project_root_from_cwd(Path.cwd())
+        if inferred is not None:
+            os.environ.setdefault(DATA_ENGINE_APP_ROOT_ENV_VAR, str(inferred))
+    if args.workspace is not None:
+        os.environ[DATA_ENGINE_WORKSPACE_ROOT_ENV_VAR] = str(args.workspace.expanduser().resolve())
+
+
+def _infer_project_root_from_cwd(cwd: Path) -> Path | None:
+    candidate = cwd.expanduser().resolve()
+    if (candidate / "pyproject.toml").is_file() and (candidate / "src" / "data_engine").is_dir():
+        return candidate
+    return None
+
+
+def _run_command(args: argparse.Namespace, *, dependencies: CliDependencies) -> int:
+    if args.run_command == "tests":
+        return _run_tests(slice_name=args.slice, list_slices=args.list_slices, dependencies=dependencies)
+    raise FlowValidationError(f"Unknown run command: {args.run_command}")
+
+
+def _test_slice_args(slice_name: str, *, app_root: Path) -> tuple[str, ...]:
+    return _commands_run.test_slice_args(slice_name, app_root=app_root)
+
+
+def _run_tests(*, slice_name: str, list_slices: bool, dependencies: CliDependencies) -> int:
+    app_root = dependencies.app_state_policy.load_settings().app_root
+    return _commands_run.run_tests(slice_name=slice_name, list_slices=list_slices, app_root=app_root)
+
+
+def _doctor(*, dependencies: CliDependencies) -> int:
+    settings = dependencies.app_state_policy.load_settings()
+    paths = dependencies.workspace_service.resolve_paths()
+    return _commands_doctor.doctor(settings=settings, paths=paths)
+
+
+def _doctor_command(args: argparse.Namespace, *, dependencies: CliDependencies) -> int:
+    if getattr(args, "doctor_command", None) == "daemons":
+        return _doctor_daemons(dependencies=dependencies)
+    return _doctor(dependencies=dependencies)
+
+
+def _run_process_listing():
+    return _commands_doctor.run_process_listing()
+
+
+def _classify_process_kind(command: str) -> str | None:
+    return _commands_doctor.classify_process_kind(command)
+
+def _doctor_daemons(*, dependencies: CliDependencies) -> int:
+    settings = dependencies.app_state_policy.load_settings()
+    return _commands_doctor.doctor_daemons(
+        settings=settings,
+        workspace_service=dependencies.workspace_service,
+        process_listing_func=_run_process_listing,
+        classify_process_kind_func=_classify_process_kind,
+        read_lease_metadata_func=dependencies.shared_state_service.read_lease_metadata,
+        lease_is_stale_func=lambda paths, stale_after_seconds: dependencies.shared_state_service.lease_is_stale(
+            paths,
+            stale_after_seconds=stale_after_seconds,
+        ),
+        machine_id_text_func=machine_id_text,
+    )
+
+
+__all__ = [
+    "CliDependencies",
+    "CliDependencyFactories",
+    "_HelpFormatter",
+    "_apply_environment",
+    "_classify_process_kind",
+    "_doctor",
+    "_doctor_command",
+    "_doctor_daemons",
+    "_infer_project_root_from_cwd",
+    "_launch_desktop_ui",
+    "_launch_terminal_ui",
+    "_preferred_gui_python_executable",
+    "_run_command",
+    "_run_process_listing",
+    "_run_tests",
+    "_start_gui_subprocess",
+    "_start_surface",
+    "_test_slice_args",
+    "_workspace_vscode_settings",
+    "build_default_cli_dependencies",
+    "build_parser",
+    "default_cli_dependency_factories",
+    "main",
+]