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

data_engine/ui/cli/commands_doctor.py

@@ -0,0 +1,178 @@
+"""Environment and daemon diagnostics for the CLI surface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+import sys
+from typing import Any, Callable
+
+from data_engine.authoring.model import FlowValidationError
+from data_engine.domain import ClassifiedProcessInfo, DoctorCheck, ProcessInfo, WorkspaceLeaseDiagnostic
+from data_engine.platform.workspace_models import authored_workspace_is_available, machine_id_text
+
+
+def doctor(*, settings: Any, paths: Any) -> int:
+    checks: list[DoctorCheck] = []
+
+    def add(status: str, message: str) -> None:
+        checks.append(DoctorCheck(status=status, message=message))
+
+    add("OK", f"app root: {settings.app_root}")
+    add("OK", f"python executable: {Path(sys.executable).expanduser()}")
+    add("OK" if settings.settings_path.is_file() else "WARN", f"workspace settings: {settings.settings_path}")
+    add("OK" if settings.state_root.exists() else "WARN", f"state root: {settings.state_root}")
+    add("OK" if settings.runtime_root.exists() else "WARN", f"runtime root: {settings.runtime_root}")
+    if settings.workspace_collection_root is None:
+        add("WARN", "workspace collection root: not configured")
+    else:
+        add("OK" if settings.workspace_collection_root.is_dir() else "WARN", f"workspace collection root: {settings.workspace_collection_root}")
+    if paths.workspace_configured:
+        add("OK" if paths.workspace_root.is_dir() else "WARN", f"workspace root: {paths.workspace_root}")
+        add("OK" if paths.flow_modules_dir.is_dir() else "WARN", f"flow modules dir: {paths.flow_modules_dir}")
+        add("OK" if (paths.workspace_root / ".vscode" / "settings.json").is_file() else "WARN", f"VS Code settings: {paths.workspace_root / '.vscode' / 'settings.json'}")
+        add("OK" if authored_workspace_is_available(paths) else "WARN", f"authored workspace ready: {paths.workspace_root}")
+    else:
+        add("WARN", "workspace root: not configured")
+        add("WARN", "flow modules dir: not configured")
+        add("WARN", "VS Code settings: not configured")
+        add("WARN", "authored workspace ready: workspace collection root not configured")
+    add("OK" if paths.artifacts_dir.exists() else "WARN", f"artifacts dir: {paths.artifacts_dir}")
+
+    failures = 0
+    for check in checks:
+        print(f"[{check.status}] {check.message}")
+        if check.status == "FAIL":
+            failures += 1
+    return 1 if failures else 0
+
+
+def run_process_listing() -> list[ProcessInfo]:
+    result = subprocess.run(
+        ["ps", "-ax", "-o", "pid=", "-o", "ppid=", "-o", "stat=", "-o", "command="],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise FlowValidationError("Unable to inspect the local process table.")
+    rows: list[ProcessInfo] = []
+    for line in result.stdout.splitlines():
+        parts = line.strip().split(None, 3)
+        if len(parts) != 4:
+            continue
+        pid_text, ppid_text, status, command = parts
+        try:
+            pid = int(pid_text)
+            ppid = int(ppid_text)
+        except ValueError:
+            continue
+        rows.append(ProcessInfo(pid=pid, ppid=ppid, status=status, command=command))
+    return rows
+
+
+def classify_process_kind(command: str) -> str | None:
+    if "data_engine.hosts.daemon.app" in command:
+        return "daemon"
+    if "data_engine.ui.gui.launcher" in command:
+        return "gui"
+    if "data_engine.ui.tui.app" in command:
+        return "tui"
+    return None
+
+
+def doctor_daemons(
+    *,
+    settings: Any,
+    workspace_service: Any,
+    process_rows: list[ProcessInfo] | None = None,
+    process_listing_func: Callable[[], list[ProcessInfo]] = run_process_listing,
+    classify_process_kind_func: Callable[[str], str | None] = classify_process_kind,
+    read_lease_metadata_func: Callable[[Any], dict[str, Any] | None],
+    lease_is_stale_func: Callable[[Any, float], bool],
+    machine_id_text_func: Callable[[], str] = machine_id_text,
+) -> int:
+    rows = process_rows if process_rows is not None else process_listing_func()
+    relevant = [
+        ClassifiedProcessInfo(
+            pid=row.pid,
+            ppid=row.ppid,
+            status=row.status,
+            command=row.command,
+            kind=kind,
+        )
+        for row in rows
+        for kind in (classify_process_kind_func(str(row.command)),)
+        if kind is not None
+    ]
+    daemons = [row for row in relevant if row.kind == "daemon"]
+    surfaces = [row for row in relevant if row.kind in {"gui", "tui"}]
+    defunct = [row for row in daemons if row.is_defunct]
+    live_daemons = [row for row in daemons if row not in defunct]
+
+    print("Data Engine Daemon Diagnostics")
+    print("")
+    print(f"Live daemons: {len(live_daemons)}")
+    for row in live_daemons:
+        orphaned = " orphaned" if row.is_orphaned else ""
+        print(f"  daemon pid={row.pid} ppid={row.ppid} status={row.status}{orphaned}")
+
+    print("")
+    print(f"Defunct daemons: {len(defunct)}")
+    for row in defunct:
+        print(f"  defunct pid={row.pid} ppid={row.ppid} status={row.status}")
+
+    print("")
+    print(f"Related UI processes: {len(surfaces)}")
+    for row in surfaces:
+        print(f"  {row.kind} pid={row.pid} ppid={row.ppid} status={row.status}")
+
+    print("")
+    print("Workspace leases:")
+    discovered = ()
+    if settings.workspace_collection_root is not None:
+        discovered = workspace_service.discover(
+            app_root=settings.app_root,
+            workspace_collection_root=settings.workspace_collection_root,
+        )
+    any_workspace = False
+    for item in discovered:
+        any_workspace = True
+        paths = workspace_service.resolve_paths(
+            workspace_id=item.workspace_id,
+            workspace_root=item.workspace_root,
+            workspace_collection_root=settings.workspace_collection_root,
+        )
+        metadata = read_lease_metadata_func(paths)
+        if metadata is None:
+            print(f"  {item.workspace_id}: no lease metadata")
+            continue
+        pid_value = metadata.get("pid")
+        try:
+            pid = int(pid_value)
+        except (TypeError, ValueError):
+            pid = None
+        matching = next((row for row in rows if row.pid == pid), None) if pid is not None else None
+        owner = metadata.get("machine_id")
+        if matching is None:
+            status = "missing"
+        elif matching.status.startswith("Z"):
+            status = "defunct"
+        else:
+            status = "live"
+        lease_row = WorkspaceLeaseDiagnostic(
+            workspace_id=item.workspace_id,
+            lease_pid=pid,
+            state=status,
+            stale=lease_is_stale_func(paths, stale_after_seconds=30.0),
+            local_owner=owner == machine_id_text_func(),
+        )
+        stale_text = " stale" if lease_row.stale else ""
+        local_text = " local" if lease_row.local_owner else ""
+        print(
+            f"  {lease_row.workspace_id}: lease_pid={lease_row.lease_pid if lease_row.lease_pid is not None else '-'} "
+            f"state={lease_row.state}{stale_text}{local_text}"
+        )
+    if not any_workspace:
+        print("  no discovered workspaces")
+    return 0

data_engine/ui/cli/commands_run.py

@@ -0,0 +1,80 @@
+"""Curated test-running commands for the CLI surface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import subprocess
+import sys
+
+from data_engine.authoring.model import FlowValidationError
+
+TEST_SLICE_CHOICES = ("all", "unit", "ui", "qt", "tui", "integration", "live")
+
+
+def checkout_tests_dir(app_root: Path) -> Path:
+    """Return the repo-local tests directory for one checkout-style app root."""
+    tests_dir = app_root / "tests"
+    if not tests_dir.is_dir():
+        raise FlowValidationError(
+            f"Run tests is only available from a checkout-style app root with a tests directory: {app_root}"
+        )
+    return tests_dir
+
+
+def raise_open_file_limit(*, minimum_soft_limit: int = 4096) -> None:
+    """Best-effort raise of the soft open-file limit before long pytest runs."""
+    try:
+        import resource
+    except ImportError:  # pragma: no cover - non-Unix fallback
+        return
+    try:
+        soft_limit, hard_limit = resource.getrlimit(resource.RLIMIT_NOFILE)
+    except (OSError, ValueError):
+        return
+    target_limit = hard_limit if hard_limit >= 0 else minimum_soft_limit
+    target_limit = max(soft_limit, min(target_limit, minimum_soft_limit) if hard_limit >= 0 else minimum_soft_limit)
+    if hard_limit >= 0:
+        target_limit = min(hard_limit, max(soft_limit, minimum_soft_limit))
+    if target_limit <= soft_limit:
+        return
+    try:
+        resource.setrlimit(resource.RLIMIT_NOFILE, (target_limit, hard_limit))
+    except (OSError, ValueError):
+        return
+
+
+def test_slice_args(slice_name: str, *, app_root: Path) -> tuple[str, ...]:
+    tests_dir = checkout_tests_dir(app_root)
+    match slice_name:
+        case "all":
+            return (str(tests_dir),)
+        case "unit":
+            return (
+                str(tests_dir),
+                f"--ignore={tests_dir / 'test_qt_ui.py'}",
+                f"--ignore={tests_dir / 'test_tui.py'}",
+                f"--ignore={tests_dir / 'test_integration.py'}",
+                f"--ignore={tests_dir / 'test_live_runtime_suite.py'}",
+            )
+        case "ui":
+            return (str(tests_dir / "test_qt_ui.py"), str(tests_dir / "test_tui.py"))
+        case "qt":
+            return (str(tests_dir / "test_qt_ui.py"),)
+        case "tui":
+            return (str(tests_dir / "test_tui.py"),)
+        case "integration":
+            return (str(tests_dir / "test_integration.py"),)
+        case "live":
+            return (str(tests_dir / "test_live_runtime_suite.py"),)
+    raise FlowValidationError(f"Unknown test slice: {slice_name}")
+
+
+def run_tests(*, slice_name: str, list_slices: bool, app_root: Path) -> int:
+    if list_slices:
+        for name in TEST_SLICE_CHOICES:
+            print(name)
+        return 0
+    checkout_tests_dir(app_root)
+    raise_open_file_limit()
+    command = [sys.executable, "-m", "pytest", "-q", *test_slice_args(slice_name, app_root=app_root)]
+    return subprocess.run(command, check=False).returncode

data_engine/ui/cli/commands_start.py

@@ -0,0 +1,100 @@
+"""Surface-launch command helpers for the CLI surface."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import time
+
+from data_engine.authoring.model import FlowValidationError
+
+
+def start_surface(surface: str) -> int:
+    """Launch one operator surface."""
+    if surface == "gui":
+        return start_gui_subprocess()
+    if surface == "tui":
+        return launch_terminal_ui()
+    raise FlowValidationError(f"Unknown surface: {surface}")
+
+
+def preferred_gui_python_executable() -> Path:
+    """Return the preferred Python executable for detached GUI launches."""
+    # Preserve the active interpreter path instead of resolving symlinks.
+    # On macOS, resolving a venv python can collapse back to the base framework
+    # interpreter, which loses the installed package context for child launches.
+    executable = Path(sys.executable).expanduser()
+    if os.name == "nt":
+        candidate = executable.with_name("pythonw.exe")
+        return candidate if candidate.exists() else executable
+    if sys.platform == "darwin":
+        candidate = executable.with_name("pythonw")
+        return candidate if candidate.exists() else executable
+    return executable
+
+
+def start_gui_subprocess() -> int:
+    """Spawn the desktop GUI in a detached process."""
+    command = [str(preferred_gui_python_executable()), "-m", "data_engine.ui.gui.launcher"]
+    log_fd, log_path_text = tempfile.mkstemp(prefix="data-engine-gui-start-", suffix=".log")
+    os.close(log_fd)
+    log_path = Path(log_path_text)
+    with log_path.open("w", encoding="utf-8") as startup_log:
+        kwargs: dict[str, object] = {
+            "cwd": str(Path.cwd()),
+            "env": dict(os.environ),
+            "stdin": subprocess.DEVNULL,
+            "stdout": startup_log,
+            "stderr": startup_log,
+        }
+        if os.name == "nt":
+            creationflags = 0
+            detached_process = getattr(subprocess, "DETACHED_PROCESS", 0)
+            create_new_process_group = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+            creationflags = detached_process | create_new_process_group
+            if creationflags:
+                kwargs["creationflags"] = creationflags
+        else:
+            kwargs["start_new_session"] = True
+        process = subprocess.Popen(command, **kwargs)
+    time.sleep(0.3)
+    exit_code = process.poll()
+    if exit_code is not None:
+        startup_output = log_path.read_text(encoding="utf-8").strip()
+        print(
+            "Data Engine GUI exited during startup."
+            f" See startup log: {log_path}"
+            + (f"\n{startup_output}" if startup_output else ""),
+            file=sys.stderr,
+        )
+        return exit_code or 1
+    print("Started Data Engine GUI.")
+    return 0
+
+
+def launch_desktop_ui(*, theme_name: str | None = None) -> int:
+    """Launch the PySide desktop UI in the current process."""
+    from data_engine.ui.gui.launcher import launch
+
+    launch(theme_name=theme_name or "light")
+    return 0
+
+
+def launch_terminal_ui() -> int:
+    """Launch the Textual terminal UI in the current process."""
+    from data_engine.ui.tui.app import main as tui_main
+
+    tui_main()
+    return 0
+
+
+__all__ = [
+    "launch_desktop_ui",
+    "launch_terminal_ui",
+    "preferred_gui_python_executable",
+    "start_gui_subprocess",
+    "start_surface",
+]

data_engine/ui/cli/commands_workspace.py

@@ -0,0 +1,97 @@
+"""Workspace scaffolding helpers for the CLI surface."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from data_engine.authoring.model import FlowValidationError
+from data_engine.platform.workspace_models import (
+    WORKSPACE_CONFIG_DIR_NAME,
+    WORKSPACE_DATABASES_DIR_NAME,
+    WORKSPACE_FLOW_HELPERS_DIR_NAME,
+    WORKSPACE_FLOW_MODULES_DIR_NAME,
+    WorkspaceSettings,
+    validate_workspace_id,
+)
+from data_engine.services.workspace_provisioning import (
+    collection_vscode_settings as build_collection_vscode_settings,
+    checkout_source_dir,
+    checkout_tests_dir,
+    write_collection_vscode_settings as persist_collection_vscode_settings,
+    workspace_vscode_settings as build_workspace_vscode_settings,
+    write_workspace_vscode_settings as persist_workspace_vscode_settings,
+)
+
+
+def create_command(args, *, dependencies) -> int:
+    """Dispatch one create subcommand."""
+    if args.create_command == "workspace":
+        return create_workspace(args.path, dependencies=dependencies)
+    raise FlowValidationError(f"Unknown create command: {args.create_command}")
+
+
+def create_workspace(path: Path, *, dependencies) -> int:
+    """Create one authored workspace scaffold and select it as default."""
+    target = path.expanduser().resolve()
+    workspace_id = validate_workspace_id(target.name)
+    if target.exists():
+        if not target.is_dir():
+            raise FlowValidationError(f"Workspace path is not a directory: {target}")
+        if any(target.iterdir()):
+            raise FlowValidationError(f"Refusing to create workspace in a non-empty directory: {target}")
+    target.mkdir(parents=True, exist_ok=True)
+    for child in (
+        WORKSPACE_FLOW_MODULES_DIR_NAME,
+        f"{WORKSPACE_FLOW_MODULES_DIR_NAME}/{WORKSPACE_FLOW_HELPERS_DIR_NAME}",
+        WORKSPACE_CONFIG_DIR_NAME,
+        WORKSPACE_DATABASES_DIR_NAME,
+    ):
+        (target / child).mkdir(parents=True, exist_ok=True)
+    write_collection_vscode_settings(target.parent, dependencies=dependencies)
+    write_workspace_vscode_settings(target, dependencies=dependencies)
+    settings = dependencies.app_state_policy.load_settings()
+    dependencies.app_state_policy.write_settings(
+        WorkspaceSettings(
+            app_root=settings.app_root,
+            settings_path=settings.settings_path,
+            state_root=settings.state_root,
+            runtime_root=settings.runtime_root,
+            workspace_collection_root=target.parent,
+            default_selected=workspace_id,
+        )
+    )
+    print(f"Created workspace: {target}")
+    print(f"Selected default workspace: {workspace_id}")
+    return 0
+
+
+def workspace_vscode_settings(workspace_root: Path, *, app_root: Path) -> dict[str, object]:
+    """Return VS Code settings for one workspace, with dev extras only for checkout roots."""
+    return build_workspace_vscode_settings(workspace_root, app_root=app_root)
+
+
+def collection_vscode_settings(collection_root: Path, *, app_root: Path) -> dict[str, object]:
+    """Return VS Code settings for one workspace collection root."""
+    return build_collection_vscode_settings(collection_root, app_root=app_root)
+
+
+def write_collection_vscode_settings(collection_root: Path, *, dependencies) -> None:
+    """Write the collection-root VS Code settings file."""
+    app_root = dependencies.app_state_policy.load_settings().app_root
+    persist_collection_vscode_settings(collection_root, app_root=app_root, overwrite=True)
+
+
+def write_workspace_vscode_settings(workspace_root: Path, *, dependencies) -> None:
+    """Write the workspace-local VS Code settings file."""
+    app_root = dependencies.app_state_policy.load_settings().app_root
+    persist_workspace_vscode_settings(workspace_root, app_root=app_root, overwrite=True)
+
+
+__all__ = [
+    "collection_vscode_settings",
+    "create_command",
+    "create_workspace",
+    "write_collection_vscode_settings",
+    "workspace_vscode_settings",
+    "write_workspace_vscode_settings",
+]

data_engine/ui/cli/dependencies.py

@@ -0,0 +1,44 @@
+"""Dependency wiring for the CLI surface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+from data_engine.platform.workspace_policy import AppStatePolicy
+from data_engine.services import SharedStateService, WorkspaceService
+
+
+@dataclass(frozen=True)
+class CliDependencies:
+    """Concrete collaborators used by the public CLI surface."""
+
+    app_state_policy: AppStatePolicy
+    shared_state_service: SharedStateService
+    workspace_service: WorkspaceService
+
+
+@dataclass(frozen=True)
+class CliDependencyFactories:
+    """Factories for the CLI's default concrete collaborators."""
+
+    app_state_policy_factory: Callable[[], AppStatePolicy]
+    shared_state_service_factory: Callable[[], SharedStateService]
+    workspace_service_factory: Callable[[], WorkspaceService]
+
+
+def default_cli_dependency_factories() -> CliDependencyFactories:
+    return CliDependencyFactories(
+        app_state_policy_factory=AppStatePolicy,
+        shared_state_service_factory=SharedStateService,
+        workspace_service_factory=WorkspaceService,
+    )
+
+
+def build_default_cli_dependencies(*, factories: CliDependencyFactories | None = None) -> CliDependencies:
+    factories = factories or default_cli_dependency_factories()
+    return CliDependencies(
+        app_state_policy=factories.app_state_policy_factory(),
+        shared_state_service=factories.shared_state_service_factory(),
+        workspace_service=factories.workspace_service_factory(),
+    )

data_engine/ui/cli/parser.py

@@ -0,0 +1,56 @@
+"""Argument parser construction for the CLI surface."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from data_engine.platform.identity import APP_DISPLAY_NAME, APP_DISTRIBUTION_NAME
+from data_engine.ui.cli.commands_run import TEST_SLICE_CHOICES
+
+
+class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """Readable CLI help with preserved examples."""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=APP_DISTRIBUTION_NAME,
+        description=f"{APP_DISPLAY_NAME} command-line interface.",
+        epilog=(
+            "Examples:\n"
+            "  data-engine start gui\n"
+            "  data-engine start tui\n"
+            "  data-engine create workspace ~/workspaces/claims\n"
+            "  data-engine run tests\n"
+            "  data-engine run tests all\n"
+            "  data-engine doctor"
+        ),
+        formatter_class=_HelpFormatter,
+    )
+    parser.add_argument("--workspace", type=Path, help="Authored workspace root to use.")
+    parser.add_argument("--app-root", type=Path, help=f"{APP_DISPLAY_NAME} project/app root used for local artifacts.")
+
+    subparsers = parser.add_subparsers(dest="command", required=True, metavar="{start,create,run,doctor}")
+
+    start_parser = subparsers.add_parser("start", help="Launch one Data Engine operator surface.")
+    start_subparsers = start_parser.add_subparsers(dest="start_command", required=True, metavar="{gui,tui}")
+    start_subparsers.add_parser("gui", help="Launch the desktop GUI.")
+    start_subparsers.add_parser("tui", help="Launch the terminal UI.")
+
+    create_parser = subparsers.add_parser("create", help="Create Data Engine scaffolding.")
+    create_subparsers = create_parser.add_subparsers(dest="create_command", required=True, metavar="{workspace}")
+    workspace_parser = create_subparsers.add_parser("workspace", help="Create and select one authored workspace.")
+    workspace_parser.add_argument("path", type=Path, help="Path to the workspace root to create.")
+
+    run_parser = subparsers.add_parser("run", help="Run helpful project tasks.")
+    run_subparsers = run_parser.add_subparsers(dest="run_command", required=True, metavar="{tests}")
+    tests_parser = run_subparsers.add_parser("tests", help="Run one curated test slice.")
+    tests_parser.add_argument("slice", nargs="?", default="unit", choices=TEST_SLICE_CHOICES, help="Named test slice to run.")
+    tests_parser.add_argument("--list-slices", action="store_true", help="Print the available named test slices.")
+
+    doctor_parser = subparsers.add_parser("doctor", help="Inspect the local Data Engine environment and workspace setup.")
+    doctor_subparsers = doctor_parser.add_subparsers(dest="doctor_command", required=False, metavar="{daemons}")
+    doctor_subparsers.add_parser("daemons", help="Inspect Data Engine daemon and related process state.")
+    return parser
+

data_engine/ui/gui/__init__.py

@@ -0,0 +1,25 @@
+"""Qt GUI surface for Data Engine."""
+
+from data_engine.domain import format_log_line
+from data_engine.views import QtFlowCard, flow_category
+
+__all__ = [
+    "DataEngineWindow",
+    "QtFlowCard",
+    "flow_category",
+    "format_log_line",
+    "launch",
+    "main",
+]
+
+
+def __getattr__(name: str):
+    if name == "DataEngineWindow":
+        from data_engine.ui.gui.app import DataEngineWindow
+
+        return DataEngineWindow
+    if name in {"launch", "main"}:
+        from data_engine.ui.gui.launcher import launch, main
+
+        return {"launch": launch, "main": main}[name]
+    raise AttributeError(name)