ferp 0.7.1__py3-none-any.whl

ferp/core/bundle_installer.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from textual.worker import Worker, WorkerState
+
+from ferp.core.dependency_manager import ScriptDependencyManager
+from ferp.widgets.scripts import ScriptManager
+
+if TYPE_CHECKING:
+    from ferp.core.app import Ferp
+
+
+@dataclass(frozen=True)
+class ScriptBundleManifest:
+    id: str
+    name: str
+    version: str
+    target: str
+    entrypoint: str
+    readme: str | None
+    dependencies: list[str]
+    file_extensions: list[str]
+
+
+@dataclass(frozen=True)
+class InstalledBundleResult:
+    manifest: ScriptBundleManifest
+    script_path: Path
+    readme_path: Path | None
+
+
+class ScriptBundleInstaller:
+    """Handles installing zipped FSCP script bundles."""
+
+    def __init__(self, app: "Ferp") -> None:
+        self._app = app
+        self._app_root = app.app_root
+        self._scripts_dir = app.scripts_dir
+        self._config_file = app._paths.config_file
+
+    def start_install(self, bundle_path: Path) -> None:
+        self._app.notify(f"Installing bundle: {bundle_path}", timeout=3)
+        self._app.run_worker(
+            lambda: self._process_script_bundle(bundle_path),
+            group="bundle_install",
+            exclusive=True,
+            thread=True,
+        )
+
+    def handle_worker_state(self, event: Worker.StateChanged) -> bool:
+        worker = event.worker
+        if worker.group != "bundle_install":
+            return False
+
+        if event.state is WorkerState.SUCCESS:
+            result = worker.result
+            if isinstance(result, InstalledBundleResult):
+                self._handle_bundle_install_result(result)
+            return True
+
+        if event.state is WorkerState.ERROR:
+            error = worker.error or RuntimeError("Bundle installation failed.")
+            self._app.show_error(error)
+            return True
+
+        return True
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _process_script_bundle(self, bundle_path: Path) -> InstalledBundleResult:
+        path = bundle_path.expanduser()
+        if not path.exists():
+            raise FileNotFoundError(f"No bundle found at {path}")
+        if not path.is_file():
+            raise ValueError(f"Bundle path must point to a file: {path}")
+        if path.suffix.lower() != ".ferp":
+            raise ValueError("Bundles must be supplied as .ferp archives.")
+
+        with zipfile.ZipFile(path) as archive:
+            manifest_member = self._find_manifest_member(archive)
+            raw_manifest = archive.read(manifest_member).decode("utf-8")
+            manifest = self._parse_bundle_manifest(json.loads(raw_manifest))
+
+            script_member = self._resolve_archive_member(archive, manifest.entrypoint)
+            script_bytes = archive.read(script_member)
+
+            script_dir = self._scripts_dir / manifest.id
+            if script_dir.exists():
+                shutil.rmtree(script_dir)
+            script_dir.mkdir(parents=True, exist_ok=True)
+            script_target = script_dir / "script.py"
+            script_target.write_bytes(script_bytes)
+
+            readme_path: Path | None = None
+            if manifest.readme:
+                readme_member = self._resolve_archive_member(archive, manifest.readme)
+                readme_text = archive.read(readme_member).decode("utf-8")
+                readme_path = script_dir / "readme.md"
+                readme_path.write_text(readme_text, encoding="utf-8")
+
+        self._update_scripts_config(manifest, script_target)
+        dependency_manager = ScriptDependencyManager(
+            self._config_file, python_executable=sys.executable
+        )
+        dependency_manager.install_for_scripts([manifest.id])
+
+        return InstalledBundleResult(
+            manifest=manifest,
+            script_path=script_target,
+            readme_path=readme_path,
+        )
+
+    def _handle_bundle_install_result(self, result: InstalledBundleResult) -> None:
+        message = (
+            f"Bundle installed: {result.manifest.name} v{result.manifest.version} "
+            f"({result.manifest.id})"
+        )
+        self._app.notify(message, timeout=4)
+        scripts_panel = self._app.query_one(ScriptManager)
+        scripts_panel.load_scripts()
+        scripts_panel.focus()
+
+    def _find_manifest_member(self, archive: zipfile.ZipFile) -> str:
+        for name in archive.namelist():
+            normalized = name.rstrip("/")
+            if normalized.endswith("manifest.json"):
+                return name
+        raise FileNotFoundError("Bundle is missing manifest.json")
+
+    def _resolve_archive_member(self, archive: zipfile.ZipFile, reference: str) -> str:
+        normalized = reference.replace("\\", "/").strip("/")
+        if not normalized:
+            raise ValueError("Invalid reference inside bundle manifest.")
+
+        files = [
+            info.filename.rstrip("/")
+            for info in archive.infolist()
+            if not info.is_dir()
+        ]
+
+        for name in files:
+            if name == normalized:
+                return name
+
+        matches = [name for name in files if name.endswith(normalized)]
+        if not matches:
+            raise FileNotFoundError(f"Unable to locate '{reference}' in bundle.")
+        if len(matches) > 1:
+            raise ValueError(f"Reference '{reference}' is ambiguous in bundle.")
+        return matches[0]
+
+    def _parse_bundle_manifest(self, payload: dict[str, Any]) -> ScriptBundleManifest:
+        for key in ("id", "name", "version", "entrypoint", "target"):
+            if key not in payload:
+                raise ValueError(f"Manifest missing required field '{key}'.")
+
+        target = str(payload["target"])
+        if target not in {
+            "current_directory",
+            "highlighted_file",
+            "highlighted_directory",
+        }:
+            raise ValueError(
+                "Manifest 'target' must be 'current_directory', "
+                "'highlighted_file', or 'highlighted_directory'."
+            )
+
+        readme = payload.get("readme")
+        if readme is not None:
+            readme = str(readme).strip()
+            if not readme:
+                readme = None
+
+        deps_raw = payload.get("dependencies", [])
+        if deps_raw is None:
+            dependencies: list[str] = []
+        elif isinstance(deps_raw, list):
+            dependencies = [str(dep).strip() for dep in deps_raw if str(dep).strip()]
+        else:
+            raise ValueError(
+                "Manifest 'dependencies' must be an array of requirement strings."
+            )
+
+        file_ext_raw = payload.get("file_extensions", [])
+        if file_ext_raw is None:
+            file_extensions: list[str] = []
+        elif isinstance(file_ext_raw, list):
+            file_extensions = [
+                str(ext).strip() for ext in file_ext_raw if str(ext).strip()
+            ]
+        else:
+            raise ValueError("Manifest 'file_extensions' must be an array of strings.")
+
+        return ScriptBundleManifest(
+            id=str(payload["id"]),
+            name=str(payload["name"]),
+            version=str(payload["version"]),
+            target=target,
+            entrypoint=str(payload["entrypoint"]),
+            readme=readme,
+            dependencies=dependencies,
+            file_extensions=file_extensions,
+        )
+
+    def _update_scripts_config(
+        self,
+        manifest: ScriptBundleManifest,
+        script_path: Path,
+    ) -> None:
+        config_path = self._config_file
+        if not config_path.exists():
+            raise FileNotFoundError(f"Unable to locate config at {config_path}")
+
+        data = json.loads(config_path.read_text())
+        scripts = data.setdefault("scripts", [])
+
+        rel_path = script_path.relative_to(self._app_root).as_posix()
+        entry: dict[str, Any] = {
+            "id": manifest.id,
+            "name": manifest.name,
+            "version": manifest.version,
+            "script": rel_path,
+            "target": manifest.target,
+        }
+        if manifest.file_extensions:
+            entry["file_extensions"] = manifest.file_extensions
+        if manifest.dependencies:
+            entry["dependencies"] = manifest.dependencies
+
+        for index, existing in enumerate(scripts):
+            if existing.get("id") == manifest.id:
+                scripts[index] = entry
+                break
+        else:
+            scripts.append(entry)
+
+        config_path.write_text(json.dumps(data, indent=2) + "\n")

ferp/core/command_provider.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from textual.command import CommandListItem, SimpleCommand, SimpleProvider
+from textual.screen import Screen
+from textual.style import Style
+
+if TYPE_CHECKING:
+    from ferp.core.app import Ferp
+
+
+class FerpCommandProvider(SimpleProvider):
+    """Command palette provider for FERP-specific actions."""
+
+    _COMMAND_DEFS: tuple[tuple[str, str, str], ...] = (
+        (
+            "Install Script Bundle",
+            "Install a zipped FSCP script bundle into FERP.",
+            "_command_install_script_bundle",
+        ),
+        (
+            "Install/Update Default Scripts",
+            "Update scripts from the bundled defaults and overwrite config.json.",
+            "_command_install_default_scripts",
+        ),
+        (
+            "Refresh File Tree",
+            "Reload the current directory listing.",
+            "_command_refresh_file_tree",
+        ),
+        (
+            "Reload Script Catalog",
+            "Re-read script metadata from config/config.json.",
+            "_command_reload_scripts",
+        ),
+        (
+            "Open Latest Log",
+            "Open the most recent transcript log file.",
+            "_command_open_latest_log",
+        ),
+        (
+            "Open User Guide",
+            "Open the bundled FERP user guide.",
+            "_command_open_user_guide",
+        ),
+        (
+            "Show Processes",
+            "View and manage tracked script processes.",
+            "_command_show_processes",
+        ),
+        (
+            "Set Startup Directory",
+            "Update the startup directory stored in settings.json.",
+            "_command_set_startup_directory",
+        ),
+        (
+            "Sync Monday Board Cache",
+            "Fetch the Monday board and refresh publishers_cache.json.",
+            "_command_sync_monday_board",
+        ),
+        (
+            "Upgrade FERP",
+            "Run pipx upgrade.",
+            "_command_upgrade_app",
+        ),
+    )
+
+    def __init__(self, screen: Screen[Any], match_style: Style | None = None) -> None:
+        app = cast("Ferp", screen.app)
+        commands: list[CommandListItem] = [
+            SimpleCommand(label, getattr(app, handler_name), description)
+            for label, description, handler_name in self._COMMAND_DEFS
+        ]
+        super().__init__(screen, commands)
+        if match_style is not None:
+            self._SimpleProvider__match_style = match_style  # type: ignore[attr-defined]

ferp/core/dependency_manager.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Iterable, Sequence
+
+
+class ScriptDependencyManager:
+    """Install script dependencies from the user config."""
+
+    def __init__(self, config_file: Path, python_executable: str | None = None) -> None:
+        self._config_file = config_file
+        self._python_executable = python_executable or sys.executable
+
+    def install_for_scripts(self, script_ids: Iterable[str] | None = None) -> None:
+        dependencies = self._collect_dependencies(script_ids)
+        if not dependencies:
+            return
+        self._install_dependencies(dependencies)
+
+    def _collect_dependencies(self, script_ids: Iterable[str] | None) -> list[str]:
+        if not self._config_file.exists():
+            raise FileNotFoundError(f"Unable to locate config at {self._config_file}")
+
+        data = json.loads(self._config_file.read_text())
+        scripts = data.get("scripts", [])
+        selected_ids = {script_id for script_id in script_ids} if script_ids else None
+        seen: set[str] = set()
+        deps: list[str] = []
+
+        for script in scripts:
+            script_id = str(script.get("id", ""))
+            if selected_ids is not None and script_id not in selected_ids:
+                continue
+            for dep in script.get("dependencies", []) or []:
+                dep_text = str(dep).strip()
+                if not dep_text or dep_text in seen:
+                    continue
+                seen.add(dep_text)
+                deps.append(dep_text)
+
+        return deps
+
+    def _install_dependencies(self, dependencies: Sequence[str]) -> None:
+        pip_cmd = [self._python_executable, "-m", "pip", "install", *dependencies]
+        try:
+            subprocess.run(
+                pip_cmd,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as exc:
+            stderr = exc.stderr.strip() if exc.stderr else ""
+            raise RuntimeError(
+                f"Failed to install dependencies ({', '.join(dependencies)}).\n{stderr}"
+            ) from exc

ferp/core/fs_controller.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+import shutil
+import stat
+from pathlib import Path
+
+
+class FileSystemController:
+    """Encapsulates file-system mutations so the UI stays lean."""
+
+    def create_path(
+        self,
+        target: Path,
+        *,
+        is_directory: bool,
+        overwrite: bool = False,
+    ) -> Path:
+        if target.exists():
+            if not overwrite:
+                raise FileExistsError(f"{target} already exists")
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+
+        if is_directory:
+            target.mkdir(parents=True, exist_ok=True)
+        else:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.touch()
+
+        return target
+
+    def delete_path(self, target: Path) -> None:
+        if not target.exists():
+            return
+
+        if target.is_dir():
+            def _handle_remove_error(func, path, exc):
+                if isinstance(exc, PermissionError):
+                    os.chmod(path, stat.S_IWRITE)
+                    func(path)
+                    return
+                raise exc
+
+            shutil.rmtree(target, onexc=_handle_remove_error)
+        else:
+            target.unlink()
+
+    def rename_path(
+        self, source: Path, destination: Path, *, overwrite: bool = False
+    ) -> Path:
+        if not source.exists():
+            raise FileNotFoundError(f"{source} does not exist")
+
+        if destination.exists() and destination != source:
+            if not overwrite:
+                raise FileExistsError(f"{destination} already exists")
+            if destination.is_dir():
+                shutil.rmtree(destination)
+            else:
+                destination.unlink()
+
+        if source == destination:
+            return destination
+
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        source.rename(destination)
+        return destination

ferp/core/fs_watcher.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
+from textual.timer import Timer
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers.api import ObservedWatch
+
+if TYPE_CHECKING:
+    from watchdog.observers import Observer as WatchdogObserver
+else:
+    from watchdog.observers import Observer as WatchdogObserver
+
+
+class DirectoryChangeHandler(FileSystemEventHandler):
+    """Watchdog handler that forwards filesystem activity to the UI thread."""
+
+    def __init__(self, notify_change: Callable[[], None]) -> None:
+        self._notify_change = notify_change
+
+    def on_any_event(self, event: FileSystemEvent | None = None) -> None:  # type: ignore[override]
+        self._notify_change()
+
+
+class FileTreeWatcher:
+    """Manages filesystem watching and debounced refreshes for the FileTree."""
+
+    def __init__(
+        self,
+        *,
+        call_from_thread: Callable[[Callable[[], None]], object | None],
+        refresh_callback: Callable[[], None],
+        missing_callback: Callable[[Path], None] | None = None,
+        snapshot_func: Callable[[Path], tuple[str, ...]],
+        timer_factory: Callable[[float, Callable[[], None]], Timer],
+        debounce_seconds: float = 2.0,
+    ) -> None:
+        self._call_from_thread = call_from_thread
+        self._refresh_callback = refresh_callback
+        self._missing_callback = missing_callback
+        self._snapshot_func = snapshot_func
+        self._timer_factory = timer_factory
+        self._debounce_seconds = debounce_seconds
+
+        self._observer: WatchdogObserver | None = None  # type: ignore
+        self._watch: ObservedWatch | None = None
+        self._handler: DirectoryChangeHandler | None = None
+        self._current_directory: Path | None = None
+        self._refresh_timer: Timer | None = None
+        self._last_snapshot: tuple[str, ...] | None = None
+
+    def start(self, directory: Path) -> None:
+        """Ensure the watcher is running and observing the provided directory."""
+        self._current_directory = directory
+        self._ensure_observer()
+        self._restart_watch(directory)
+
+    def stop(self) -> None:
+        """Tear down the watch and stop the observer."""
+        if self._refresh_timer is not None:
+            self._refresh_timer.stop()
+            self._refresh_timer = None
+
+        observer = self._observer
+        if observer is not None:
+            if self._watch is not None:
+                try:
+                    observer.unschedule(self._watch)
+                except Exception:
+                    pass
+                self._watch = None
+            observer.stop()
+            observer.join(timeout=1)
+
+        self._observer = None
+        self._handler = None
+
+    def update_snapshot(self, directory: Path) -> None:
+        """Record the latest directory signature to prevent redundant refreshes."""
+        if not directory.exists():
+            self._last_snapshot = None
+            return
+        self._last_snapshot = self._snapshot_func(directory)
+        self._current_directory = directory
+
+    def _ensure_observer(self) -> None:
+        if self._observer is not None:
+            return
+
+        handler = DirectoryChangeHandler(
+            notify_change=self._notify_from_thread,
+        )
+        observer = WatchdogObserver()
+        observer.daemon = True
+        observer.start()
+
+        self._handler = handler
+        self._observer = observer
+
+    def _restart_watch(self, directory: Path) -> None:
+        observer = self._observer
+        handler = self._handler
+        if observer is None or handler is None:
+            return
+
+        if self._watch is not None:
+            try:
+                observer.unschedule(self._watch)
+            except Exception:
+                pass
+            self._watch = None
+
+        if not directory.exists():
+            return
+
+        try:
+            self._watch = observer.schedule(handler, str(directory), recursive=False)
+        except Exception:
+            self._watch = None
+
+    def _queue_refresh(self) -> None:
+        if self._refresh_timer is not None:
+            return
+        self._refresh_timer = self._timer_factory(
+            self._debounce_seconds, self._complete_refresh
+        )
+
+    def _complete_refresh(self) -> None:
+        self._refresh_timer = None
+        directory = self._current_directory
+        if directory is None or not directory.exists():
+            if directory is not None and self._missing_callback is not None:
+                self._missing_callback(directory)
+            return
+
+        signature = self._snapshot_func(directory)
+        if signature == self._last_snapshot:
+            return
+
+        self._refresh_callback()
+
+    def _notify_from_thread(self) -> None:
+        self._call_from_thread(self._queue_refresh)

ferp/core/messages.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+from textual.message import Message
+
+from ferp.domain.scripts import Script
+
+
+class NavigateRequest(Message):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        super().__init__()
+
+
+class RunScriptRequest(Message):
+    def __init__(self, script: Script) -> None:
+        self.script = script
+        super().__init__()
+
+
+class DirectorySelectRequest(Message):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        super().__init__()
+
+
+class ShowReadmeRequest(Message):
+    def __init__(self, script: Script, readme_path: Path | None) -> None:
+        super().__init__()
+        self.script = script
+        self.readme_path = readme_path
+
+
+class CreatePathRequest(Message):
+    def __init__(self, base: Path, *, is_directory: bool) -> None:
+        super().__init__()
+        self.base = base
+        self.is_directory = is_directory
+
+
+class DeletePathRequest(Message):
+    def __init__(self, target: Path) -> None:
+        super().__init__()
+        self.target = target
+
+
+class RenamePathRequest(Message):
+    def __init__(self, target: Path) -> None:
+        super().__init__()
+        self.target = target