pulse-framework 0.1.62__py3-none-any.whl

pulse/cli/models.py

@@ -0,0 +1,35 @@
+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
+	ready_pattern: str | None = None  # Regex pattern to detect when command is ready
+	on_ready: Callable[[], None] | None = None  # Callback when ready_pattern matches

pulse/cli/packages.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+# Helpers for parsing JavaScript package specifiers used by Pulse's CLI.
+#
+# Goals:
+# - Extract a canonical npm/bun package name from import sources used in React components
+#   (reject relative paths; allow aliases like "@/" and "~/"; ignore URLs/absolute paths).
+# - Parse dependency specs that may include an optional version (e.g., "pkg@^2", "@scope/name@1").
+
+
+def is_relative_source(src: str) -> bool:
+	return src.startswith("./") or src.startswith("../")
+
+
+def is_alias_source(src: str) -> bool:
+	return src.startswith("@/") or src.startswith("~/")
+
+
+def is_url_or_absolute(src: str) -> bool:
+	return (
+		src.startswith("http://") or src.startswith("https://") or src.startswith("/")
+	)
+
+
+def parse_dependency_spec(spec: str) -> tuple[str, str | None]:
+	"""Parse a dependency spec into (name, version) where version may be None.
+
+	Accepts:
+	  - "some-pkg"
+	  - "some-pkg@^1.2.3"
+	  - "@scope/name"
+	  - "@scope/name@2"
+
+	Ignores any subpath suffix (e.g., "pkg/sub/path"). For scoped packages with versions,
+	splits on the last '@' to avoid confusing the scope '@'.
+	"""
+
+	if spec.startswith("@"):
+		# Scoped: @scope/name[@version][/subpath]
+		s = spec[1:]
+		i = s.find("/")
+		if i == -1:
+			return "@" + s, None
+		scope = s[:i]
+		rest = s[i + 1 :]
+		# head may be 'name' or 'name@version'
+		j = rest.find("/")
+		head = rest if j == -1 else rest[:j]
+		if "@" in head:
+			name_part, ver = head.split("@", 1)
+		else:
+			name_part, ver = head, None
+		return f"@{scope}/{name_part}", (ver or None)
+
+	# Unscoped: name[@version][/subpath]
+	head = spec.split("/", 1)[0]
+	if "@" in head:
+		name, ver = head.split("@", 1)
+		return name, (ver or None)
+	return head, None
+
+
+def parse_install_spec(src_or_spec: str) -> str | None:
+	"""Unified parser that:
+	- Rejects relative paths by raising ValueError.
+	- Returns None for alias ("@/", "~/"), URLs, and absolute paths.
+	- Returns a normalized install spec: "name" or "name@version".
+	- Accepts sources or dependency specs, and strips subpaths.
+	"""
+
+	if is_relative_source(src_or_spec):
+		raise ValueError(
+			f"React component import source '{src_or_spec}' must not be relative (./ or ../). Use a package, '@/...' or '~/...' alias instead."
+		)
+	if is_alias_source(src_or_spec) or is_url_or_absolute(src_or_spec):
+		return None
+	name, ver = parse_dependency_spec(src_or_spec)
+	return f"{name}@{ver}" if ver else name
+
+
+# ---------------------------- Version resolution ----------------------------
+
+
+class VersionConflict(Exception):
+	pass
+
+
+def pick_more_specific(a: str | None, b: str | None) -> str | None:
+	"""Pick the more specific semver constraint between two strings.
+
+	Heuristic only (no full semver solver):
+	  - Exact versions (e.g., "1.2.3") outrank range prefixes ("^", "~", ">=", "<=", ">", "<").
+	  - Between ranges, prefer the one with a longer string (assume more specific).
+	  - If one is None, return the other.
+	  - If equal, return either.
+	"""
+
+	if not a:
+		return b
+	if not b:
+		return a
+
+	# Exact version detection: purely digits and dots
+	def is_exact(v: str) -> bool:
+		return bool(v) and all(part.isdigit() for part in v.split("."))
+
+	a_exact = is_exact(a)
+	b_exact = is_exact(b)
+	if a_exact and b_exact:
+		return a if a == b else None  # same exact or conflict
+	if a_exact:
+		return a
+	if b_exact:
+		return b
+
+	# If both are ranges, prefer higher version if possible (heuristic)
+	if a.startswith(("^", "~")) and b.startswith(("^", "~")):
+		av = a[1:]
+		bv = b[1:]
+		# Basic version comparison for digits
+		try:
+			a_parts = [int(p) for p in av.split(".") if p.isdigit()]
+			b_parts = [int(p) for p in bv.split(".") if p.isdigit()]
+			if a_parts > b_parts:
+				return a
+			if b_parts > a_parts:
+				return b
+		except ValueError:
+			pass
+
+	# Prefer longer constraint as proxy for specificity
+	return a if len(a) >= len(b) else b
+
+
+def resolve_versions(
+	constraints: dict[str, list[str | None]],
+) -> dict[str, str | None]:
+	"""Resolve version constraints per package.
+
+	Input: { name: [ver1, ver2, None, ...] }
+	Output: { name: resolved_version_or_None }
+	Raises VersionConflict if constraints are incompatible under our heuristic.
+	"""
+	resolved: dict[str, str | None] = {}
+	for name, vers in constraints.items():
+		cur: str | None = None
+		for v in vers:
+			cur = pick_more_specific(cur, v)
+			if cur is None and v is not None:
+				# irreconcilable (two different exact versions)
+				raise VersionConflict(f"Conflicting versions for {name}: {vers}")
+		resolved[name] = cur
+	return resolved
+
+
+# ----------------------------- package.json utils ----------------------------
+
+
+def load_package_json(web_root: Path) -> dict[str, Any]:
+	pkg_path = web_root / "package.json"
+	try:
+		data = json.loads(pkg_path.read_text())
+		if isinstance(data, dict):
+			return data
+	except Exception:
+		pass
+	return {}
+
+
+def get_pkg_spec(pkg_json: dict[str, Any], name: str) -> str | None:
+	for field in ("dependencies", "devDependencies"):
+		section = pkg_json.get(field)
+		if isinstance(section, dict) and name in section:
+			spec = section.get(name)
+			if isinstance(spec, str):
+				return spec.strip()
+	return None
+
+
+def is_workspace_spec(spec: str) -> bool:
+	return spec.strip().startswith("workspace:")
+
+
+def _split_constraint(spec: str) -> tuple[str, str | None]:
+	s = spec.strip()
+	if not s:
+		return "unknown", None
+	if s[0] in ("^", "~"):
+		return (s[0], s[1:])
+	# exact version like 1 or 1.2 or 1.2.3
+	if all(part.isdigit() for part in s.split(".")):
+		return ("=", s)
+	return "unknown", s
+
+
+def _parse_major_minor(ver: str | None) -> tuple[int | None, int | None]:
+	if not ver:
+		return None, None
+	try:
+		parts = ver.split(".")
+		major = int(parts[0]) if len(parts) >= 1 and parts[0].isdigit() else None
+		minor = int(parts[1]) if len(parts) >= 2 and parts[1].isdigit() else None
+		return major, minor
+	except Exception:
+		return None, None
+
+
+def spec_satisfies(required: str | None, existing: str | None) -> bool:
+	if required is None:
+		return True
+	if not existing:
+		return False
+	if is_workspace_spec(existing):
+		return True
+	rk, rv = _split_constraint(required)
+	ek, ev = _split_constraint(existing)
+	rmaj, rmin = _parse_major_minor(rv)
+	emaj, emin = _parse_major_minor(ev)
+
+	# Exact required
+	if rk == "=":
+		if ek == "=" and rv == ev:
+			return True
+		# Accept common ranges that include the exact version
+		if ek == "^" and emaj is not None and rmaj is not None and emaj == rmaj:
+			return True
+		if (
+			ek == "~"
+			and emaj is not None
+			and emin is not None
+			and rmaj is not None
+			and rmin is not None
+			and emaj == rmaj
+			and emin == rmin
+		):
+			return True
+		return False
+
+	# Caret required: same major acceptable
+	if rk == "^" and rmaj is not None:
+		if ek == "=" and emaj == rmaj:
+			return True
+		if ek == "^" and emaj == rmaj:
+			return True
+		if ek == "~" and emaj == rmaj:
+			return True
+		return False
+
+	# Tilde required: same major+minor acceptable
+	if rk == "~" and rmaj is not None and rmin is not None:
+		if ek == "=" and emaj == rmaj and emin == rmin:
+			return True
+		if ek == "~" and emaj == rmaj and emin == rmin:
+			return True
+		return False
+
+	# Unknown required; fallback to equality
+	return required == existing

pulse/cli/processes.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+import contextlib
+import os
+import pty
+import re
+import select
+import signal
+import subprocess
+import sys
+from collections.abc import Sequence
+from io import TextIOBase
+from typing import TypeVar, cast
+
+from pulse.cli.helpers import os_family
+from pulse.cli.logging import TagMode
+from pulse.cli.models import CommandSpec
+
+_K = TypeVar("_K", int, str)
+
+# ANSI color codes for tagged output
+ANSI_CODES = {
+	"cyan": "\033[36m",
+	"orange1": "\033[38;5;208m",
+	"reset": "\033[0m",
+}
+
+# Tag colors mapping (used only in colored mode)
+TAG_COLORS = {"server": "cyan", "web": "orange1"}
+
+# Regex to strip ANSI escape codes
+ANSI_ESCAPE = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+
+def execute_commands(
+	commands: Sequence[CommandSpec],
+	*,
+	tag_mode: TagMode = "colored",
+) -> int:
+	"""Run the provided commands, streaming tagged output to stdout.
+
+	Args:
+		commands: List of command specifications to run
+		tag_mode: How to display process tags:
+			- "colored": Show [server]/[web] with ANSI colors (dev mode)
+			- "plain": Show [server]/[web] without colors (ci/prod mode)
+	"""
+	if not commands:
+		return 0
+
+	# Avoid pty.fork() in multi-threaded environments (like pytest) to prevent
+	# "DeprecationWarning: This process is multi-threaded, use of forkpty() may lead to deadlocks"
+	# Also skip pty on Windows or if fork is unavailable
+	in_pytest = "pytest" in sys.modules
+	if os_family() == "windows" or not hasattr(pty, "fork") or in_pytest:
+		return _run_without_pty(commands, tag_mode=tag_mode)
+
+	return _run_with_pty(commands, tag_mode=tag_mode)
+
+
+def _call_on_spawn(spec: CommandSpec) -> None:
+	"""Call the on_spawn callback if it exists."""
+	if spec.on_spawn:
+		try:
+			spec.on_spawn()
+		except Exception:
+			pass
+
+
+def _check_on_ready(
+	spec: CommandSpec,
+	line: str,
+	ready_flags: dict[_K, bool],
+	key: _K,
+) -> None:
+	"""Check if line matches ready_pattern and call on_ready if needed."""
+	if spec.ready_pattern and not ready_flags[key]:
+		# Strip ANSI codes before matching
+		clean_line = ANSI_ESCAPE.sub("", line)
+		if re.search(spec.ready_pattern, clean_line):
+			ready_flags[key] = True
+			if spec.on_ready:
+				try:
+					spec.on_ready()
+				except Exception:
+					pass
+
+
+def _run_with_pty(
+	commands: Sequence[CommandSpec],
+	*,
+	tag_mode: TagMode,
+) -> int:
+	procs: list[tuple[str, int, int]] = []
+	fd_to_spec: dict[int, CommandSpec] = {}
+	buffers: dict[int, bytearray] = {}
+	ready_flags: dict[int, bool] = {}
+
+	try:
+		for spec in commands:
+			pid, fd = pty.fork()
+			if pid == 0:
+				if spec.cwd:
+					os.chdir(spec.cwd)
+				os.execvpe(spec.args[0], spec.args, spec.env)
+			else:
+				fcntl = __import__("fcntl")
+				fcntl.fcntl(fd, fcntl.F_SETFL, os.O_NONBLOCK)
+				procs.append((spec.name, pid, fd))
+				fd_to_spec[fd] = spec
+				buffers[fd] = bytearray()
+				ready_flags[fd] = False
+				_call_on_spawn(spec)
+
+		while procs:
+			for tag, pid, fd in list(procs):
+				try:
+					wpid, status = os.waitpid(pid, os.WNOHANG)
+					if wpid == pid:
+						procs.remove((tag, pid, fd))
+						_close_fd(fd)
+				except ChildProcessError:
+					procs.remove((tag, pid, fd))
+					_close_fd(fd)
+
+			if not procs:
+				break
+
+			readable = [fd for _, _, fd in procs]
+			try:
+				ready, _, _ = select.select(readable, [], [], 0.1)
+			except (OSError, ValueError):
+				break
+
+			for fd in ready:
+				try:
+					data = os.read(fd, 4096)
+					if not data:
+						continue
+					buffers[fd].extend(data)
+					while b"\n" in buffers[fd]:
+						line, remainder = buffers[fd].split(b"\n", 1)
+						buffers[fd] = remainder
+						decoded = line.decode(errors="replace")
+						if decoded:
+							spec = fd_to_spec[fd]
+							_write_tagged_line(spec.name, decoded, tag_mode)
+							_check_on_ready(spec, decoded, ready_flags, fd)
+				except OSError:
+					continue
+
+		exit_codes: list[int] = []
+		for _tag, pid, fd in procs:
+			try:
+				_, status = os.waitpid(pid, 0)
+				exit_codes.append(os.WEXITSTATUS(status) if os.WIFEXITED(status) else 1)
+			except Exception:
+				pass
+			_close_fd(fd)
+
+		return max(exit_codes) if exit_codes else 0
+
+	except KeyboardInterrupt:
+		for _tag, pid, _fd in procs:
+			try:
+				os.kill(pid, signal.SIGTERM)
+			except Exception:
+				pass
+		return 130
+	finally:
+		for _tag, pid, fd in procs:
+			try:
+				os.kill(pid, signal.SIGKILL)
+			except Exception:
+				pass
+			_close_fd(fd)
+
+
+def _run_without_pty(
+	commands: Sequence[CommandSpec],
+	*,
+	tag_mode: TagMode,
+) -> int:
+	from selectors import EVENT_READ, DefaultSelector
+
+	procs: list[tuple[str, subprocess.Popen[str], CommandSpec]] = []
+	completed_codes: list[int] = []
+	selector = DefaultSelector()
+	ready_flags: dict[str, bool] = {}
+
+	try:
+		for spec in commands:
+			proc = subprocess.Popen(
+				spec.args,
+				cwd=spec.cwd,
+				env=spec.env,
+				stdout=subprocess.PIPE,
+				stderr=subprocess.STDOUT,
+				text=True,
+				bufsize=1,
+				universal_newlines=True,
+			)
+			_call_on_spawn(spec)
+			if proc.stdout:
+				selector.register(proc.stdout, EVENT_READ, data=spec.name)
+			ready_flags[spec.name] = False
+			procs.append((spec.name, proc, spec))
+
+		while procs:
+			events = selector.select(timeout=0.1)
+			for key, _mask in events:
+				name = key.data
+				stream = key.fileobj
+				if isinstance(stream, int):
+					continue
+				# stream is now guaranteed to be a file-like object
+				line = cast(TextIOBase, stream).readline()
+				if line:
+					_write_tagged_line(name, line.rstrip("\n"), tag_mode)
+					spec = next((s for n, _, s in procs if n == name), None)
+					if spec:
+						_check_on_ready(spec, line, ready_flags, name)
+				else:
+					selector.unregister(stream)
+			remaining: list[tuple[str, subprocess.Popen[str], CommandSpec]] = []
+			for name, proc, spec in procs:
+				code = proc.poll()
+				if code is None:
+					remaining.append((name, proc, spec))
+				else:
+					completed_codes.append(code)
+					if proc.stdout:
+						with contextlib.suppress(Exception):
+							selector.unregister(proc.stdout)
+							proc.stdout.close()
+			procs = remaining
+	except KeyboardInterrupt:
+		for _name, proc, _spec in procs:
+			with contextlib.suppress(Exception):
+				proc.terminate()
+		return 130
+	finally:
+		for _name, proc, _spec in procs:
+			with contextlib.suppress(Exception):
+				proc.terminate()
+			with contextlib.suppress(Exception):
+				proc.wait(timeout=1)
+		for key in list(selector.get_map().values()):
+			with contextlib.suppress(Exception):
+				selector.unregister(key.fileobj)
+		selector.close()
+
+	exit_codes = completed_codes + [
+		proc.returncode or 0 for _name, proc, _spec in procs
+	]
+	return max(exit_codes) if exit_codes else 0
+
+
+def _write_tagged_line(name: str, message: str, tag_mode: TagMode) -> None:
+	"""Write a line of output with optional process tag.
+
+	Args:
+		name: Process name (e.g., "server", "web")
+		message: The line of output to write
+		tag_mode: How to display the tag:
+			- "colored": Show [name] with ANSI colors
+			- "plain": Show [name] without colors
+	"""
+	# Filter out unwanted web server messages
+	clean_message = ANSI_ESCAPE.sub("", message)
+	if (
+		"Network: use --host to expose" in clean_message
+		or "press h + enter to show help" in clean_message
+		or "➜  Local:" in clean_message
+	):
+		return
+
+	if tag_mode == "colored":
+		color = ANSI_CODES.get(TAG_COLORS.get(name, ""), "")
+		if color:
+			sys.stdout.write(f"{color}[{name}]{ANSI_CODES['reset']} {message}\n")
+		else:
+			sys.stdout.write(f"[{name}] {message}\n")
+	else:
+		# Plain mode: tags without color
+		sys.stdout.write(f"[{name}] {message}\n")
+	sys.stdout.flush()
+
+
+def _close_fd(fd: int) -> None:
+	with contextlib.suppress(Exception):
+		os.close(fd)

pulse/cli/secrets.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import secrets
+from pathlib import Path
+
+from pulse.cli.helpers import ensure_gitignore_has
+
+
+def resolve_dev_secret(app_path: Path | None) -> str | None:
+	"""Return or create a persisted development secret for the given app path."""
+	if app_path is None:
+		return None
+
+	try:
+		root = app_path if app_path.is_dir() else app_path.parent
+		secret_dir = root / ".pulse"
+		secret_dir.mkdir(parents=True, exist_ok=True)
+
+		secret_file = secret_dir / "secret"
+		if secret_file.exists():
+			try:
+				content = secret_file.read_text().strip()
+				if content:
+					return content
+			except Exception:
+				return None
+
+		secret_value = secrets.token_urlsafe(32)
+		try:
+			secret_file.write_text(secret_value)
+		except Exception:
+			# Best effort; secret still returned for current session
+			pass
+
+		ensure_gitignore_has(root, ".pulse/")
+
+		return secret_value
+	except Exception:
+		return None

pulse/cli/uvicorn_log_config.py

@@ -0,0 +1,87 @@
+"""Custom logging configuration for uvicorn to filter noisy requests."""
+
+import logging
+from typing import Any, override
+
+
+class FilterNoisyRequests(logging.Filter):
+	"""Filter out noisy requests from uvicorn access logs."""
+
+	# Patterns to suppress (static assets, node_modules, vite internals)
+	SUPPRESS_PATTERNS: tuple[str, ...] = (
+		"/node_modules/",
+		"/@vite/",
+		"/%40vite/",  # URL-encoded @vite
+		"/@fs/",
+		"/%40fs/",  # URL-encoded @fs
+		"/@id/",
+		"/%40id/",  # URL-encoded @id
+		"/@react-refresh",
+		"/app/",  # React Router source files served by Vite
+		".js?v=",
+		".css?v=",
+		".css ",  # CSS files (space indicates end of path in log)
+		".tsx ",  # TSX source files
+		".ts ",  # TS source files
+		".js ",  # JS files
+		".map",
+		"/favicon.ico",
+		"/.well-known/",  # Browser/DevTools well-known endpoints
+		"connection open",
+		"connection closed",
+		"connection rejected",
+		"304 Not Modified",  # Usually just cache hits, not interesting
+	)
+
+	@override
+	def filter(self, record: logging.LogRecord) -> bool:
+		"""Return False to suppress log records matching noise patterns."""
+		message = record.getMessage()
+		# Suppress if message contains any noise pattern
+		return not any(pattern in message for pattern in self.SUPPRESS_PATTERNS)
+
+
+def get_log_config(default_level: str = "info") -> dict[str, Any]:
+	"""Get uvicorn logging config with noise filter."""
+	return {
+		"version": 1,
+		"disable_existing_loggers": False,
+		"filters": {
+			"filter_noisy_requests": {
+				"()": "pulse.cli.uvicorn_log_config.FilterNoisyRequests",
+			},
+		},
+		"formatters": {
+			"default": {
+				"()": "uvicorn.logging.DefaultFormatter",
+				"fmt": "%(message)s",
+				"use_colors": None,
+			},
+			"access": {
+				"()": "uvicorn.logging.AccessFormatter",
+				"fmt": '%(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
+			},
+		},
+		"handlers": {
+			"default": {
+				"formatter": "default",
+				"class": "logging.StreamHandler",
+				"stream": "ext://sys.stderr",
+			},
+			"access": {
+				"formatter": "access",
+				"class": "logging.StreamHandler",
+				"stream": "ext://sys.stdout",
+				"filters": ["filter_noisy_requests"],
+			},
+		},
+		"loggers": {
+			"uvicorn": {"handlers": ["default"], "level": default_level.upper()},
+			"uvicorn.error": {"level": "INFO"},
+			"uvicorn.access": {
+				"handlers": ["access"],
+				"level": "INFO",
+				"propagate": False,
+			},
+		},
+	}