pulse-framework 0.1.62__py3-none-any.whl

pulse/cli/dependencies.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from pulse.cli.packages import (
+	VersionConflict,
+	get_pkg_spec,
+	is_workspace_spec,
+	load_package_json,
+	parse_dependency_spec,
+	parse_install_spec,
+	resolve_versions,
+	spec_satisfies,
+)
+from pulse.transpiler.imports import get_registered_imports
+
+
+def convert_pep440_to_semver(python_version: str) -> str:
+	"""Convert PEP 440 version format to NPM semver format.
+
+	PEP 440 formats:
+	- 0.1.37a1 -> 0.1.37-alpha.1
+	- 0.1.37b1 -> 0.1.37-beta.1
+	- 0.1.37rc1 -> 0.1.37-rc.1
+	- 0.1.37.dev1 -> 0.1.37-dev.1
+
+	Non-pre-release versions are returned unchanged.
+	"""
+	# Match pre-release patterns: version followed by a/b/rc/dev + number
+	# PEP 440: a1, b1, rc1, dev1, alpha1, beta1, etc.
+	pattern = r"^(\d+\.\d+\.\d+)([a-z]+)(\d+)$"
+	match = re.match(pattern, python_version)
+
+	if match:
+		base_version = match.group(1)
+		prerelease_type = match.group(2)
+		prerelease_num = match.group(3)
+
+		# Map PEP 440 prerelease types to NPM semver
+		type_map = {
+			"a": "alpha",
+			"alpha": "alpha",
+			"b": "beta",
+			"beta": "beta",
+			"rc": "rc",
+			"c": "rc",  # PEP 440 also allows 'c' for release candidate
+			"dev": "dev",
+		}
+
+		npm_type = type_map.get(prerelease_type.lower(), prerelease_type)
+		return f"{base_version}-{npm_type}.{prerelease_num}"
+
+	# Also handle .dev format (e.g., 0.1.37.dev1)
+	pattern2 = r"^(\d+\.\d+\.\d+)\.dev(\d+)$"
+	match2 = re.match(pattern2, python_version)
+	if match2:
+		base_version = match2.group(1)
+		dev_num = match2.group(2)
+		return f"{base_version}-dev.{dev_num}"
+
+	# No pre-release, return as-is
+	return python_version
+
+
+class DependencyError(RuntimeError):
+	"""Base error for dependency preparation failures."""
+
+
+class DependencyResolutionError(DependencyError):
+	"""Raised when component constraints cannot be resolved."""
+
+
+class DependencyCommandError(DependencyError):
+	"""Raised when Bun commands fail to run."""
+
+
+@dataclass
+class DependencyPlan:
+	"""Return value describing the command required to sync dependencies."""
+
+	command: list[str]
+	to_add: Sequence[str]
+
+
+def get_required_dependencies(
+	web_root: Path,
+	*,
+	pulse_version: str,
+) -> dict[str, str | None]:
+	"""Get the required dependencies for a Pulse app."""
+	if not web_root.exists():
+		raise DependencyError(f"Directory not found: {web_root}")
+
+	constraints: dict[str, list[str | None]] = {
+		"pulse-ui-client": [pulse_version],
+	}
+
+	# New transpiler v2 imports
+	for imp in get_registered_imports():
+		if imp.src:
+			try:
+				spec = parse_install_spec(imp.src)
+			except ValueError as exc:
+				# We might want to be more lenient here or at least log it,
+				# but following existing pattern of raising DependencyError
+				raise DependencyError(str(exc)) from None
+			if spec:
+				name_only, ver = parse_dependency_spec(spec)
+				constraints.setdefault(name_only, []).append(ver)
+				if imp.version:
+					constraints.setdefault(name_only, []).append(imp.version)
+
+	try:
+		resolved = resolve_versions(constraints)
+	except VersionConflict as exc:
+		raise DependencyResolutionError(str(exc)) from None
+
+	desired: dict[str, str | None] = dict(resolved)
+	for pkg in [
+		"react-router",
+		"@react-router/node",
+		"@react-router/serve",
+		"@react-router/dev",
+	]:
+		desired.setdefault(pkg, "^7")
+
+	return desired
+
+
+def check_web_dependencies(
+	web_root: Path,
+	*,
+	pulse_version: str,
+) -> list[str]:
+	"""Check if web dependencies are in sync and return list of packages that need to be added/updated."""
+	desired = get_required_dependencies(
+		web_root=web_root,
+		pulse_version=pulse_version,
+	)
+	pkg_json = load_package_json(web_root)
+
+	to_add: list[str] = []
+	for name, req_ver in sorted(desired.items()):
+		effective = req_ver
+		if name == "pulse-ui-client":
+			effective = convert_pep440_to_semver(pulse_version)
+
+		existing = get_pkg_spec(pkg_json, name)
+		if existing is None:
+			to_add.append(f"{name}@{effective}" if effective else name)
+			continue
+
+		if is_workspace_spec(existing):
+			continue
+
+		if spec_satisfies(effective, existing):
+			continue
+
+		to_add.append(f"{name}@{effective}" if effective else name)
+
+	return to_add
+
+
+def prepare_web_dependencies(
+	web_root: Path,
+	*,
+	pulse_version: str,
+) -> DependencyPlan | None:
+	"""Inspect registered components and return the Bun command needed to sync dependencies."""
+	to_add = check_web_dependencies(
+		web_root=web_root,
+		pulse_version=pulse_version,
+	)
+
+	if to_add:
+		return DependencyPlan(command=["bun", "add", *to_add], to_add=to_add)
+
+	return DependencyPlan(command=["bun", "i"], to_add=())

pulse/cli/folder_lock.py

@@ -0,0 +1,134 @@
+"""
+Folder lock management.
+
+Provides a FolderLock context manager that coordinates across processes and
+Uvicorn reloads using environment variables.
+
+Example: prevent multiple Pulse dev instances per web root.
+"""
+
+import json
+import os
+import platform
+import socket
+import time
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+from pulse.cli.helpers import ensure_gitignore_has
+
+
+def is_process_alive(pid: int) -> bool:
+	"""Check if a process with the given PID is running."""
+	try:
+		# On POSIX, signal 0 checks for existence without killing
+		os.kill(pid, 0)
+	except ProcessLookupError:
+		return False
+	except PermissionError:
+		# Process exists but we may not have permission
+		return True
+	except Exception:
+		# Best-effort: assume alive if uncertain
+		return True
+	return True
+
+
+def _read_lock(lock_path: Path) -> dict[str, Any] | None:
+	"""Read and parse lock file contents."""
+	try:
+		data = json.loads(lock_path.read_text())
+		if isinstance(data, dict):
+			return data
+	except Exception:
+		return None
+	return None
+
+
+def _write_gitignore_for_lock(lock_path: Path) -> None:
+	"""Add lock file to .gitignore if not already present."""
+
+	ensure_gitignore_has(lock_path.parent, lock_path.name)
+
+
+def _create_lock_file(lock_path: Path) -> None:
+	"""Create a lock file with current process information."""
+	lock_path = Path(lock_path)
+	_write_gitignore_for_lock(lock_path)
+
+	if lock_path.exists():
+		info = _read_lock(lock_path) or {}
+		pid = int(info.get("pid", 0) or 0)
+		if pid and is_process_alive(pid):
+			raise RuntimeError(
+				f"Another Pulse dev instance appears to be running (pid={pid}) for {lock_path.parent}."
+			)
+		# Stale lock; continue to overwrite
+
+	payload = {
+		"pid": os.getpid(),
+		"created_at": int(time.time()),
+		"hostname": socket.gethostname(),
+		"platform": platform.platform(),
+		"python": platform.python_version(),
+		"cwd": os.getcwd(),
+	}
+	try:
+		lock_path.parent.mkdir(parents=True, exist_ok=True)
+		lock_path.write_text(json.dumps(payload))
+	except Exception as exc:
+		raise RuntimeError(f"Failed to create lock file at {lock_path}: {exc}") from exc
+
+
+def _remove_lock_file(lock_path: Path) -> None:
+	"""Remove lock file (best-effort)."""
+	try:
+		Path(lock_path).unlink(missing_ok=True)
+	except Exception:
+		# Best-effort cleanup
+		pass
+
+
+def lock_path_for_web_root(web_root: Path, filename: str = ".pulse/lock") -> Path:
+	"""Return the lock file path for a given web root."""
+	return Path(web_root) / filename
+
+
+class FolderLock:
+	"""
+	Context manager for folder lock management.
+
+	Coordinates across processes and Uvicorn reloads using environment variables.
+	The process that creates the lock (typically the CLI) sets PULSE_LOCK_OWNER.
+	Child processes (uvicorn workers, reloaded processes) inherit this env var
+	and know not to delete the lock on exit.
+
+	Example:
+	    with FolderLock(web_root):
+	        # Protected region
+	        pass
+	"""
+
+	def __init__(self, web_root: Path, *, filename: str = ".pulse/lock"):
+		"""
+		Initialize FolderLock.
+
+		Args:
+		    web_root: Path to the web root directory
+		    filename: Name of the lock file (default: ".pulse/lock")
+		"""
+		self.lock_path: Path = lock_path_for_web_root(web_root, filename)
+
+	def __enter__(self):
+		_create_lock_file(self.lock_path)
+		return self
+
+	def __exit__(
+		self,
+		exc_type: type[BaseException] | None,
+		exc_val: BaseException | None,
+		exc_tb: TracebackType | None,
+	) -> bool:
+		_remove_lock_file(self.lock_path)
+		return False

pulse/cli/helpers.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import platform
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal, TypedDict
+
+import typer
+
+from pulse.cli.models import AppLoadResult
+
+if TYPE_CHECKING:
+	from pulse.cli.logging import CLILogger
+
+
+def os_family() -> Literal["windows", "mac", "linux"]:
+	s = platform.system().lower()
+	if "windows" in s:
+		return "windows"
+	if "darwin" in s or "mac" in s:
+		return "mac"
+	return "linux"
+
+
+class ParsedAppTarget(TypedDict):
+	mode: Literal["path", "module"]
+	module_name: str
+	app_var: str
+	file_path: Path | None
+	server_cwd: Path | None
+
+
+def _module_path_from_file(file_path: Path) -> tuple[str, Path]:
+	"""Compute the module import path for a file within a package hierarchy.
+	Returns (module_path, server_cwd). server_cwd is the directory that should be
+	used as the working directory so that importing module_path works.
+	"""
+	file_path = file_path.resolve()
+	is_init = file_path.name == "__init__.py"
+	parts: list[str] = [] if is_init else [file_path.stem]
+	current = file_path.parent
+	# Default to the file's parent when not inside a package
+	top_package_parent = current
+	while (current / "__init__.py").exists():
+		parts.insert(0, current.name)
+		top_package_parent = current.parent
+		current = current.parent
+	module_path = ".".join(parts)
+	server_cwd = top_package_parent
+	return module_path, server_cwd
+
+
+def parse_app_target(target: str) -> ParsedAppTarget:
+	"""Parse an app target which can be either:
+	- a filesystem path to a Python file with optional ":var" (default var is "app"), e.g. "examples/main.py:app"
+	- a module path in uvicorn style with a required ":var", e.g. "examples.main:app"
+
+	Returns a dict describing how to import/run it.
+	"""
+	# Split optional ":var" specifier once from the right
+	# Handle Windows drive letters by checking if the colon is followed by a path separator
+	if ":" in target:
+		# Check if this looks like a Windows drive letter (e.g., "C:\path" or "C:/path")
+		colon_pos = target.rfind(":")
+		if colon_pos > 0 and colon_pos < len(target) - 1:
+			char_after_colon = target[colon_pos + 1]
+			if char_after_colon in ["\\", "/"]:
+				# This is a Windows drive letter, not a variable specifier
+				path_or_module, app_var = target, "app"
+			else:
+				# This is a variable specifier
+				path_or_module, app_var = target.rsplit(":", 1)
+				app_var = app_var or "app"
+		else:
+			# Single colon at end, treat as variable specifier
+			path_or_module, app_var = target.rsplit(":", 1)
+			app_var = app_var or "app"
+	else:
+		path_or_module, app_var = target, "app"
+
+	p = Path(path_or_module)
+	if p.exists():
+		if p.is_dir():
+			# If a package directory is passed, try __init__.py semantics by using the directory name as module
+			init_file = p / "__init__.py"
+			if init_file.exists():
+				module_name, server_cwd = _module_path_from_file(init_file)
+				file_path = init_file
+			else:
+				module_name = p.name
+				file_path = None
+				server_cwd = p.parent.resolve()
+		else:
+			file_path = p.resolve()
+			module_name, server_cwd = _module_path_from_file(file_path)
+		return {
+			"mode": "path",
+			"module_name": module_name,
+			"app_var": app_var,
+			"file_path": file_path,
+			"server_cwd": server_cwd,
+		}
+
+	# Treat as module import path
+	module_name = path_or_module
+	return {
+		"mode": "module",
+		"module_name": module_name,
+		"app_var": app_var,
+		"file_path": None,
+		"server_cwd": None,
+	}
+
+
+def load_app_from_target(target: str, logger: CLILogger | None = None) -> AppLoadResult:
+	"""Load an App instance from either a file path (with optional :var) or a module path (uvicorn style).
+
+	Args:
+		target: The app target string (file path or module path)
+		logger: Optional CLILogger for error output. If not provided, uses basic print/traceback.
+	"""
+	# Avoid circular import
+	from pulse.app import App
+
+	def _log_error(message: str) -> None:
+		if logger:
+			logger.error(message)
+		else:
+			print(f"Error: {message}")
+
+	def _log_warning(message: str) -> None:
+		if logger:
+			logger.warning(message)
+		else:
+			print(f"Warning: {message}")
+
+	def _print_exception() -> None:
+		if logger:
+			logger.print_exception()
+		else:
+			import traceback
+
+			traceback.print_exc()
+
+	parsed = parse_app_target(target)
+
+	module_name = parsed["module_name"]
+	app_var = parsed["app_var"]
+	app_file: Path | None = None
+	app_dir: Path | None = None
+
+	if parsed["mode"] == "path":
+		file_path = parsed["file_path"]
+		if file_path is None:
+			_log_error(f"Could not determine a Python file from: {target}")
+			raise typer.Exit(1)
+
+		sys.path.insert(0, str(file_path.parent.absolute()))
+		try:
+			spec = importlib.util.spec_from_file_location(module_name, file_path)
+			if spec is None or spec.loader is None:
+				_log_error(f"Could not load module from: {file_path}")
+				raise typer.Exit(1)
+			module = importlib.util.module_from_spec(spec)
+			sys.modules[spec.name] = module
+			spec.loader.exec_module(module)
+		except typer.Exit:
+			raise
+		except Exception:
+			_log_error(f"Error loading {file_path}")
+			_print_exception()
+			raise typer.Exit(1) from None
+		finally:
+			if str(file_path.parent.absolute()) in sys.path:
+				sys.path.remove(str(file_path.parent.absolute()))
+
+		app_file = file_path.resolve()
+		app_dir = file_path.parent.resolve()
+		loaded_module = module
+	else:
+		# module mode
+		try:
+			module = importlib.import_module(module_name)  # type: ignore[name-defined]
+		except Exception:
+			_log_error(f"Error importing module: {module_name}")
+			_print_exception()
+			raise typer.Exit(1) from None
+
+		# Try to set env paths from the resolved module file
+		file_attr = getattr(module, "__file__", None)
+		if file_attr:
+			fp = Path(file_attr)
+			app_file = fp.resolve()
+			app_dir = fp.parent.resolve()
+		loaded_module = module
+
+	# Fetch the app attribute
+	if not hasattr(loaded_module, app_var):
+		_log_error(f"App variable '{app_var}' not found in {module_name}")
+		raise typer.Exit(1)
+	app_candidate = getattr(loaded_module, app_var)
+	if not isinstance(app_candidate, App):
+		_log_error(f"'{app_var}' in {module_name} is not a pulse.App instance")
+		raise typer.Exit(1)
+	if not app_candidate.routes:
+		_log_warning("No routes found")
+	return AppLoadResult(
+		target=target,
+		mode=parsed["mode"],
+		app=app_candidate,
+		module_name=module_name,
+		app_var=app_var,
+		app_file=app_file,
+		app_dir=app_dir,
+		server_cwd=parsed["server_cwd"],
+	)
+
+
+def ensure_gitignore_has(root: Path, *patterns: str) -> None:
+	"""
+	Ensure .gitignore in root contains the specified patterns.
+	Non-fatal: silently ignores errors.
+
+	Args:
+	    root: Directory containing (or to contain) .gitignore
+	    *patterns: Patterns to ensure are in .gitignore
+	"""
+	if not patterns:
+		return
+
+	try:
+		gitignore_path = root / ".gitignore"
+
+		if gitignore_path.exists():
+			content = gitignore_path.read_text()
+			# Parse existing entries (split on whitespace to handle various formats)
+			existing = set(content.split())
+			missing = [p for p in patterns if p not in existing]
+
+			if missing:
+				# Add missing patterns
+				additions = "\n".join(missing)
+				gitignore_path.write_text(f"{content.rstrip()}\n{additions}\n")
+		else:
+			# Create new .gitignore with all patterns
+			gitignore_path.write_text("\n".join(patterns) + "\n")
+	except Exception:
+		# Non-fatal; ignore gitignore failures
+		pass
+
+
+def install_hints_for_mkcert() -> list[str]:
+	fam = os_family()
+	if fam == "mac":
+		return [
+			"brew install mkcert nss",
+			"mkcert -install",
+		]
+	if fam == "windows":
+		return [
+			"choco install mkcert    # or: winget install FiloSottile.mkcert",
+			"mkcert -install",
+		]
+	return [
+		"sudo apt install -y mkcert libnss3-tools    # Debian/Ubuntu",
+		"# or: sudo dnf install -y mkcert nss-tools   # Fedora",
+		"# or: sudo pacman -Syu mkcert nss           # Arch",
+		"mkcert -install",
+	]

pulse/cli/logging.py

@@ -0,0 +1,102 @@
+"""
+Mode-aware CLI logging for Pulse.
+
+In dev mode, uses Rich Console with colors.
+In ci/prod mode or with --plain, uses plain print().
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Literal
+
+from pulse.env import PulseEnv
+
+if TYPE_CHECKING:
+	from rich.console import Console
+
+TagMode = Literal["colored", "plain"]
+
+
+class CLILogger:
+	"""Mode-aware CLI logger that adapts output based on pulse environment.
+
+	Args:
+		mode: The pulse environment mode (dev, ci, prod)
+		plain: Force plain output without colors, even in dev mode
+	"""
+
+	mode: PulseEnv
+	plain: bool
+	_console: Console | None
+
+	def __init__(self, mode: PulseEnv = "dev", *, plain: bool = False):
+		self.mode = mode
+		self.plain = plain
+		self._console = None
+		if mode == "dev" and not plain:
+			from rich.console import Console
+
+			self._console = Console()
+
+	@property
+	def is_plain(self) -> bool:
+		"""Return True if using plain output (ci/prod mode or --plain flag)."""
+		return self.mode != "dev" or self.plain
+
+	def print(self, message: str) -> None:
+		"""Print a message."""
+		if self._console:
+			self._console.print(message)
+		else:
+			print(message)
+
+	def error(self, message: str) -> None:
+		"""Print an error message."""
+		if self._console:
+			self._console.print(f"[red]Error:[/red] {message}")
+		else:
+			print(f"Error: {message}")
+
+	def success(self, message: str) -> None:
+		"""Print a success message."""
+		if self._console:
+			self._console.print(f"[green]✓[/green] {message}")
+		else:
+			print(f"Done: {message}")
+
+	def warning(self, message: str) -> None:
+		"""Print a warning message."""
+		if self._console:
+			self._console.print(f"[yellow]Warning:[/yellow] {message}")
+		else:
+			print(f"Warning: {message}")
+
+	def print_exception(self) -> None:
+		"""Print the current exception."""
+		if self._console:
+			self._console.print_exception()
+		else:
+			import traceback
+
+			traceback.print_exc()
+
+	def get_tag_mode(self) -> TagMode:
+		"""Return tag mode for process output: colored in dev, plain in ci/prod."""
+		return "plain" if self.is_plain else "colored"
+
+	def write_ready_announcement(
+		self, address: str, port: int, server_url: str
+	) -> None:
+		"""Write the 'Pulse is ready' announcement."""
+		if self._console:
+			self._console.print("")
+			self._console.print(
+				f"[bold green]Ready:[/bold green] [bold cyan][link={server_url}]{server_url}[/link][/bold cyan]"
+			)
+			self._console.print("")
+		else:
+			print("")
+			print(f"Ready: {server_url}")
+			print("")
+		sys.stdout.flush()