pulse-framework 0.1.37__py3-none-any.whl → 0.1.38a2__py3-none-any.whl

pulse/cli/dependencies.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+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.react_component import ReactComponent, registered_react_components
+
+
+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,
+	component_provider: Callable[
+		[], Iterable[ReactComponent[Any]]
+	] = registered_react_components,
+) -> 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}")
+
+	try:
+		components = list(component_provider())
+	except Exception as exc:
+		raise DependencyError("Unable to inspect registered React components") from exc
+
+	constraints: dict[str, list[str | None]] = {
+		"pulse-ui-client": [pulse_version],
+	}
+
+	for comp in components:
+		src = getattr(comp, "src", None)
+		component_pkg_name: str | None = None
+		if src:
+			try:
+				spec = parse_install_spec(src)
+			except ValueError as exc:
+				raise DependencyError(str(exc)) from None
+			if spec:
+				name_only, ver = parse_dependency_spec(spec)
+				constraints.setdefault(name_only, []).append(ver)
+				component_pkg_name = name_only
+
+		comp_version = getattr(comp, "version", None)
+		if comp_version and component_pkg_name:
+			constraints.setdefault(component_pkg_name, []).append(comp_version)
+
+		for extra in getattr(comp, "extra_imports", []):
+			extra_src = getattr(extra, "src", None) if extra is not None else None
+			if not extra_src:
+				continue
+			try:
+				spec2 = parse_install_spec(extra_src)
+			except ValueError as exc:
+				raise DependencyError(str(exc)) from None
+			if spec2:
+				name_only2, ver2 = parse_dependency_spec(spec2)
+				constraints.setdefault(name_only2, []).append(ver2)
+
+	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,
+	component_provider: Callable[
+		[], Iterable[ReactComponent[Any]]
+	] = registered_react_components,
+) -> 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,
+		component_provider=component_provider,
+	)
+	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,
+	component_provider: Callable[
+		[], Iterable[ReactComponent[Any]]
+	] = registered_react_components,
+) -> 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,
+		component_provider=component_provider,
+	)
+
+	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

@@ -1,7 +1,6 @@
 import importlib
 import importlib.util
 import platform
-import socket
 import sys
 from pathlib import Path
 from typing import Literal, TypedDict
@@ -9,8 +8,7 @@ from typing import Literal, TypedDict
 import typer
 from rich.console import Console
 
-from pulse.app import App
-from pulse.env import env
+from pulse.cli.models import AppLoadResult
 
 
 def os_family() -> Literal["windows", "mac", "linux"]:
@@ -22,20 +20,6 @@ def os_family() -> Literal["windows", "mac", "linux"]:
 	return "linux"
 
 
-def find_available_port(start_port: int = 8000, max_attempts: int = 100) -> int:
-	"""Find an available port starting from start_port."""
-	for port in range(start_port, start_port + max_attempts):
-		try:
-			with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-				s.bind(("localhost", port))
-				return port
-		except OSError:
-			continue
-	raise RuntimeError(
-		f"Could not find an available port after {max_attempts} attempts starting from {start_port}"
-	)
-
-
 class ParsedAppTarget(TypedDict):
 	mode: Literal["path", "module"]
 	module_name: str
@@ -126,8 +110,11 @@ def parse_app_target(target: str) -> ParsedAppTarget:
 	}
 
 
-def load_app_from_file(file_path: str | Path) -> App:
-	"""Load routes from a Python file (supports both App instances and global @ps.route decorators)."""
+def load_app_from_file(file_path: str | Path) -> AppLoadResult:
+	"""Load routes from a Python file and return app context details."""
+	# Avoid circular import
+	from pulse.app import App
+
 	file_path = Path(file_path)
 
 	if not file_path.exists():
@@ -138,10 +125,6 @@ def load_app_from_file(file_path: str | Path) -> App:
 		typer.echo(f"❌ File must be a Python file (.py): {file_path}")
 		raise typer.Exit(1)
 
-	# Set env so downstream codegen can resolve paths relative to the app file
-	env.pulse_app_file = str(file_path.absolute())
-	env.pulse_app_dir = str(file_path.parent.absolute())
-
 	# clear_routes()
 	sys.path.insert(0, str(file_path.parent.absolute()))
 
@@ -158,7 +141,16 @@ def load_app_from_file(file_path: str | Path) -> App:
 			app_instance = module.app
 			if not app_instance.routes:
 				typer.echo(f"⚠️  No routes found in {file_path}")
-			return app_instance
+			return AppLoadResult(
+				target=str(file_path),
+				mode="path",
+				app=app_instance,
+				module_name="user_app",
+				app_var="app",
+				app_file=file_path.resolve(),
+				app_dir=file_path.parent.resolve(),
+				server_cwd=file_path.parent.resolve(),
+			)
 
 		typer.echo(f"⚠️  No app found in {file_path}")
 		raise typer.Exit(1)
@@ -173,24 +165,28 @@ def load_app_from_file(file_path: str | Path) -> App:
 			sys.path.remove(str(file_path.parent.absolute()))
 
 
-def load_app_from_target(target: str) -> App:
+def load_app_from_target(target: str) -> AppLoadResult:
 	"""Load an App instance from either a file path (with optional :var) or a module path (uvicorn style)."""
+
+	# Avoid circulart import
+	from pulse.app import App
+
 	parsed = parse_app_target(target)
 
-	# Set env for downstream codegen resolution
+	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:
 			typer.echo(f"❌ Could not determine a Python file from: {target}")
 			raise typer.Exit(1)
-		env.pulse_app_file = str(file_path.absolute())
-		env.pulse_app_dir = str(file_path.parent.absolute())
 
 		sys.path.insert(0, str(file_path.parent.absolute()))
 		try:
-			spec = importlib.util.spec_from_file_location(
-				parsed["module_name"], file_path
-			)
+			spec = importlib.util.spec_from_file_location(module_name, file_path)
 			if spec is None or spec.loader is None:
 				typer.echo(f"❌ Could not load module from: {file_path}")
 				raise typer.Exit(1)
@@ -206,13 +202,16 @@ def load_app_from_target(target: str) -> App:
 			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(parsed["module_name"])  # type: ignore[name-defined]
+			module = importlib.import_module(module_name)  # type: ignore[name-defined]
 		except Exception:
 			console = Console()
-			console.log(f"❌ Error importing module: {parsed['module_name']}")
+			console.log(f"❌ Error importing module: {module_name}")
 			console.print_exception()
 			raise typer.Exit(1) from None
 
@@ -220,23 +219,63 @@ def load_app_from_target(target: str) -> App:
 		file_attr = getattr(module, "__file__", None)
 		if file_attr:
 			fp = Path(file_attr)
-			env.pulse_app_file = str(fp.absolute())
-			env.pulse_app_dir = str(fp.parent.absolute())
+			app_file = fp.resolve()
+			app_dir = fp.parent.resolve()
+		loaded_module = module
 
 	# Fetch the app attribute
-	var_name = parsed["app_var"]
-	if not hasattr(module, var_name):
-		typer.echo(f"❌ App variable '{var_name}' not found in {parsed['module_name']}")
+	if not hasattr(loaded_module, app_var):
+		typer.echo(f"❌ App variable '{app_var}' not found in {module_name}")
 		raise typer.Exit(1)
-	app_candidate = getattr(module, var_name)
+	app_candidate = getattr(loaded_module, app_var)
 	if not isinstance(app_candidate, App):
-		typer.echo(
-			f"❌ '{var_name}' in {parsed['module_name']} is not a pulse.App instance"
-		)
+		typer.echo(f"❌ '{app_var}' in {module_name} is not a pulse.App instance")
 		raise typer.Exit(1)
 	if not app_candidate.routes:
 		typer.echo("⚠️  No routes found")
-	return app_candidate
+	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]:

pulse/cli/models.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable, Literal
+
+if TYPE_CHECKING:
+	from pulse.app import App
+
+
+@dataclass(slots=True)
+class AppLoadResult:
+	"""Description of a loaded Pulse app and related filesystem context."""
+
+	target: str
+	mode: Literal["path", "module"]
+	app: App
+	module_name: str
+	app_var: str
+	app_file: Path | None
+	app_dir: Path | None
+	server_cwd: Path | None
+
+
+@dataclass(slots=True)
+class CommandSpec:
+	"""Instructions for launching a subprocess associated with the CLI."""
+
+	name: str
+	args: list[str]
+	cwd: Path
+	env: dict[str, str]
+	on_spawn: Callable[[], None] | None = None