pcf-toolkit 0.2.5__py3-none-any.whl

pcf_toolkit/proxy/mitm.py

@@ -0,0 +1,206 @@
+"""Mitmproxy bootstrap helpers."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class MitmproxyInstall:
+    binary: Path
+    venv_dir: Path
+
+
+def managed_venv_dir() -> Path:
+    """Returns the path to the managed mitmproxy virtual environment.
+
+    Returns:
+      Path to ~/.pcf-toolkit/venvs/mitmproxy.
+    """
+    return Path.home() / ".pcf-toolkit" / "venvs" / "mitmproxy"
+
+
+def find_mitmproxy(explicit_path: Path | None = None) -> Path | None:
+    """Finds mitmproxy executable.
+
+    Searches system PATH and managed venv.
+
+    Args:
+      explicit_path: Explicit path to mitmproxy binary.
+
+    Returns:
+      Path to mitmproxy executable, or None if not found.
+    """
+    if explicit_path and explicit_path.exists():
+        return explicit_path
+
+    for candidate in ("mitmdump", "mitmproxy"):
+        resolved = shutil.which(candidate)
+        if resolved:
+            return Path(resolved)
+
+    venv_dir = managed_venv_dir()
+    for candidate in ("mitmdump", "mitmproxy"):
+        resolved = _venv_bin_path(venv_dir, candidate)
+        if resolved and resolved.exists():
+            return resolved
+
+    return None
+
+
+def ensure_mitmproxy(auto_install: bool, explicit_path: Path | None = None) -> Path:
+    """Ensures mitmproxy is available, installing if needed.
+
+    Args:
+      auto_install: If True, installs mitmproxy if not found.
+      explicit_path: Explicit path to mitmproxy binary.
+
+    Returns:
+      Path to mitmproxy executable.
+
+    Raises:
+      FileNotFoundError: If mitmproxy not found and auto_install is False.
+    """
+    existing = find_mitmproxy(explicit_path)
+    if existing:
+        return existing
+    if not auto_install:
+        raise FileNotFoundError("mitmproxy not found")
+    install = install_mitmproxy(managed_venv_dir())
+    return install.binary
+
+
+def install_mitmproxy(venv_dir: Path) -> MitmproxyInstall:
+    """Installs mitmproxy into a virtual environment.
+
+    Args:
+      venv_dir: Directory for the virtual environment.
+
+    Returns:
+      MitmproxyInstall instance with binary and venv paths.
+
+    Raises:
+      FileNotFoundError: If installation fails to produce a binary.
+    """
+    venv_dir.mkdir(parents=True, exist_ok=True)
+    python_bin = _venv_python(venv_dir)
+    if not python_bin.exists():
+        subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True)
+    python_bin = _venv_python(venv_dir)
+    _ensure_pip(python_bin)
+    subprocess.run(
+        [
+            str(python_bin),
+            "-m",
+            "pip",
+            "install",
+            "--upgrade",
+            "pip",
+        ],
+        check=True,
+    )
+    subprocess.run([str(python_bin), "-m", "pip", "install", "mitmproxy"], check=True)
+    mitm_binary = _venv_bin_path(venv_dir, "mitmdump")
+    if mitm_binary is None or not mitm_binary.exists():
+        mitm_binary = _venv_bin_path(venv_dir, "mitmproxy")
+    if mitm_binary is None:
+        raise FileNotFoundError("mitmproxy install did not produce a binary")
+    return MitmproxyInstall(binary=mitm_binary, venv_dir=venv_dir)
+
+
+def spawn_mitmproxy(
+    binary: Path,
+    addon_path: Path,
+    host: str,
+    port: int,
+    env: dict[str, str],
+    stdout=None,
+    stderr=None,
+    start_new_session: bool = False,
+    creationflags: int = 0,
+) -> subprocess.Popen:
+    """Spawns a mitmproxy process with the redirect addon.
+
+    Args:
+      binary: Path to mitmproxy executable.
+      addon_path: Path to the redirect addon script.
+      host: Hostname to listen on.
+      port: Port to listen on.
+      env: Environment variables to pass to the process.
+      stdout: Standard output handle (optional).
+      stderr: Standard error handle (optional).
+      start_new_session: If True, starts process in new session.
+      creationflags: Windows process creation flags.
+
+    Returns:
+      Popen instance for the mitmproxy process.
+    """
+    cmd = [
+        str(binary),
+        "-s",
+        str(addon_path),
+        "--listen-host",
+        host,
+        "--listen-port",
+        str(port),
+    ]
+    return subprocess.Popen(
+        cmd,
+        env=env,
+        stdout=stdout,
+        stderr=stderr,
+        start_new_session=start_new_session,
+        creationflags=creationflags,
+    )
+
+
+def _ensure_pip(python_bin: Path) -> None:
+    """Ensures pip is available in the Python installation.
+
+    Args:
+      python_bin: Path to Python executable.
+    """
+    try:
+        subprocess.run(
+            [str(python_bin), "-m", "pip", "--version"],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except subprocess.CalledProcessError:
+        subprocess.run([str(python_bin), "-m", "ensurepip"], check=True)
+
+
+def _venv_python(venv_dir: Path) -> Path:
+    """Returns the path to Python executable in a virtual environment.
+
+    Args:
+      venv_dir: Virtual environment directory.
+
+    Returns:
+      Path to Python executable.
+    """
+    if os.name == "nt":
+        return venv_dir / "Scripts" / "python.exe"
+    return venv_dir / "bin" / "python"
+
+
+def _venv_bin_path(venv_dir: Path, name: str) -> Path | None:
+    """Returns the path to an executable in a virtual environment.
+
+    Args:
+      venv_dir: Virtual environment directory.
+      name: Executable name.
+
+    Returns:
+      Path to executable, or None if venv structure is invalid.
+    """
+    bin_dir = venv_dir / ("Scripts" if os.name == "nt" else "bin")
+    if os.name == "nt":
+        return bin_dir / f"{name}.exe"
+    return bin_dir / name

pcf_toolkit/proxy/server.py

@@ -0,0 +1,50 @@
+"""Local file server helpers."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def spawn_http_server(
+    directory: Path,
+    host: str,
+    port: int,
+    stdout=None,
+    stderr=None,
+    start_new_session: bool = False,
+    creationflags: int = 0,
+) -> subprocess.Popen:
+    """Spawns a local HTTP server process.
+
+    Uses Python's built-in http.server module.
+
+    Args:
+      directory: Directory to serve files from.
+      host: Hostname to bind to.
+      port: Port to listen on.
+      stdout: Standard output handle (optional).
+      stderr: Standard error handle (optional).
+      start_new_session: If True, starts process in new session.
+      creationflags: Windows process creation flags.
+
+    Returns:
+      Popen instance for the HTTP server process.
+    """
+    cmd = [
+        sys.executable,
+        "-m",
+        "http.server",
+        str(port),
+        "--bind",
+        host,
+    ]
+    return subprocess.Popen(
+        cmd,
+        cwd=directory,
+        stdout=stdout,
+        stderr=stderr,
+        start_new_session=start_new_session,
+        creationflags=creationflags,
+    )

pcf_toolkit/py.typed

@@ -0,0 +1 @@
+

pcf_toolkit/rich_help.py

@@ -0,0 +1,173 @@
+"""Custom Rich help formatting for the CLI."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+import click
+import typer.core as core
+import typer.rich_utils as rich_utils
+from rich.align import Align
+from rich.padding import Padding
+from rich.panel import Panel
+
+
+def rich_format_help_custom(
+    *,
+    obj: click.Command | click.Group,
+    ctx: click.Context,
+    markup_mode: rich_utils.MarkupModeStrict,
+) -> None:
+    """Prints Rich-formatted help with a custom examples panel.
+
+    Args:
+      obj: Click command or group to format help for.
+      ctx: Click context.
+      markup_mode: Rich markup mode for formatting.
+    """
+    console = rich_utils._get_rich_console()
+
+    # Usage
+    console.print(
+        Padding(rich_utils.highlighter(obj.get_usage(ctx)), 1),
+        style=rich_utils.STYLE_USAGE_COMMAND,
+    )
+
+    # Main help text
+    if obj.help:
+        console.print(
+            Padding(
+                Align(
+                    rich_utils._get_help_text(
+                        obj=obj,
+                        markup_mode=markup_mode,
+                    ),
+                    pad=False,
+                ),
+                (0, 1, 1, 1),
+            )
+        )
+
+    panel_to_arguments: defaultdict[str, list[click.Argument]] = defaultdict(list)
+    panel_to_options: defaultdict[str, list[click.Option]] = defaultdict(list)
+
+    for param in obj.get_params(ctx):
+        if getattr(param, "hidden", False):
+            continue
+        if isinstance(param, click.Argument):
+            panel_name = getattr(param, rich_utils._RICH_HELP_PANEL_NAME, None) or rich_utils.ARGUMENTS_PANEL_TITLE
+            panel_to_arguments[panel_name].append(param)
+        elif isinstance(param, click.Option):
+            panel_name = getattr(param, rich_utils._RICH_HELP_PANEL_NAME, None) or rich_utils.OPTIONS_PANEL_TITLE
+            panel_to_options[panel_name].append(param)
+
+    default_arguments = panel_to_arguments.get(rich_utils.ARGUMENTS_PANEL_TITLE, [])
+    rich_utils._print_options_panel(
+        name=rich_utils.ARGUMENTS_PANEL_TITLE,
+        params=default_arguments,
+        ctx=ctx,
+        markup_mode=markup_mode,
+        console=console,
+    )
+    for panel_name, arguments in panel_to_arguments.items():
+        if panel_name == rich_utils.ARGUMENTS_PANEL_TITLE:
+            continue
+        rich_utils._print_options_panel(
+            name=panel_name,
+            params=arguments,
+            ctx=ctx,
+            markup_mode=markup_mode,
+            console=console,
+        )
+
+    default_options = panel_to_options.get(rich_utils.OPTIONS_PANEL_TITLE, [])
+    rich_utils._print_options_panel(
+        name=rich_utils.OPTIONS_PANEL_TITLE,
+        params=default_options,
+        ctx=ctx,
+        markup_mode=markup_mode,
+        console=console,
+    )
+    for panel_name, options in panel_to_options.items():
+        if panel_name == rich_utils.OPTIONS_PANEL_TITLE:
+            continue
+        rich_utils._print_options_panel(
+            name=panel_name,
+            params=options,
+            ctx=ctx,
+            markup_mode=markup_mode,
+            console=console,
+        )
+
+    if isinstance(obj, click.Group):
+        panel_to_commands: defaultdict[str, list[click.Command]] = defaultdict(list)
+        for command_name in obj.list_commands(ctx):
+            command = obj.get_command(ctx, command_name)
+            if command and not command.hidden:
+                panel_name = getattr(command, rich_utils._RICH_HELP_PANEL_NAME, None) or rich_utils.COMMANDS_PANEL_TITLE
+                panel_to_commands[panel_name].append(command)
+
+        max_cmd_len = max(
+            [len(command.name or "") for commands in panel_to_commands.values() for command in commands],
+            default=0,
+        )
+
+        default_commands = panel_to_commands.get(rich_utils.COMMANDS_PANEL_TITLE, [])
+        rich_utils._print_commands_panel(
+            name=rich_utils.COMMANDS_PANEL_TITLE,
+            commands=default_commands,
+            markup_mode=markup_mode,
+            console=console,
+            cmd_len=max_cmd_len,
+        )
+        for panel_name, commands in panel_to_commands.items():
+            if panel_name == rich_utils.COMMANDS_PANEL_TITLE:
+                continue
+            rich_utils._print_commands_panel(
+                name=panel_name,
+                commands=commands,
+                markup_mode=markup_mode,
+                console=console,
+                cmd_len=max_cmd_len,
+            )
+
+    # Custom epilog panel (no line collapsing)
+    if obj.epilog:
+        title = "Examples & Tips" if isinstance(obj, click.Group) else "Examples"
+        epilogue_text = rich_utils._make_rich_text(
+            text=obj.epilog,
+            markup_mode=markup_mode,
+        )
+        panel = Panel(
+            epilogue_text,
+            title=title,
+            title_align="left",
+            border_style="cyan",
+        )
+        console.print(Padding(panel, 1))
+
+
+class RichTyperCommand(core.TyperCommand):
+    """Typer command with custom Rich help output."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:  # type: ignore[override]
+        if not core.HAS_RICH or self.rich_markup_mode is None:
+            return super().format_help(ctx, formatter)
+        return rich_format_help_custom(
+            obj=self,
+            ctx=ctx,
+            markup_mode=self.rich_markup_mode,
+        )
+
+
+class RichTyperGroup(core.TyperGroup):
+    """Typer group with custom Rich help output."""
+
+    def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:  # type: ignore[override]
+        if not core.HAS_RICH or self.rich_markup_mode is None:
+            return super().format_help(ctx, formatter)
+        return rich_format_help_custom(
+            obj=self,
+            ctx=ctx,
+            markup_mode=self.rich_markup_mode,
+        )

pcf_toolkit/schema_snapshot.py

@@ -0,0 +1,47 @@
+"""Utilities for schema snapshot export."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+
+def load_schema_snapshot() -> str:
+    """Loads the schema snapshot JSON as a string.
+
+    Tries to load from package data first, then falls back to local files.
+
+    Returns:
+      The schema snapshot JSON content as a string.
+
+    Raises:
+      FileNotFoundError: If no schema snapshot file can be found.
+    """
+    package_path = _read_package_snapshot()
+    if package_path is not None:
+        return package_path
+
+    file_path = Path("data/schema_snapshot.json")
+    if file_path.exists():
+        return file_path.read_text(encoding="utf-8")
+
+    fallback = Path("data/spec_raw.json")
+    if fallback.exists():
+        return fallback.read_text(encoding="utf-8")
+
+    raise FileNotFoundError("schema snapshot not found")
+
+
+def _read_package_snapshot() -> str | None:
+    """Reads the schema snapshot from package data.
+
+    Returns:
+      The schema snapshot JSON content, or None if not found.
+    """
+    try:
+        with resources.files("pcf_toolkit.data").joinpath("schema_snapshot.json").open("r", encoding="utf-8") as handle:
+            return handle.read()
+    except FileNotFoundError:
+        return None
+    except ModuleNotFoundError:
+        return None

pcf_toolkit/types.py

@@ -0,0 +1,95 @@
+"""Shared types and enums for PCF manifest models."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ControlType(str, Enum):
+    """Defines the control type of a PCF component."""
+
+    STANDARD = "standard"
+    VIRTUAL = "virtual"
+
+
+class DependencyType(str, Enum):
+    """Defines the dependency type for a component."""
+
+    CONTROL = "control"
+
+
+class DependencyLoadType(str, Enum):
+    """Defines how a dependency is loaded."""
+
+    ON_DEMAND = "onDemand"
+
+
+class PlatformActionType(str, Enum):
+    """Defines platform action types."""
+
+    AFTER_PAGE_LOAD = "afterPageLoad"
+
+
+class PlatformLibraryName(str, Enum):
+    """Platform library names for React controls and platform libraries."""
+
+    REACT = "React"
+    FLUENT = "Fluent"
+
+
+class PropertyUsage(str, Enum):
+    """Usage values for property elements."""
+
+    BOUND = "bound"
+    INPUT = "input"
+    OUTPUT = "output"
+
+
+class PropertySetUsage(str, Enum):
+    """Usage values for property-set elements."""
+
+    BOUND = "bound"
+    INPUT = "input"
+
+
+class RequiredFor(str, Enum):
+    """Supported required-for values for property-dependency."""
+
+    SCHEMA = "schema"
+
+
+class TypeValue(str, Enum):
+    """Supported data types for property and type elements."""
+
+    CURRENCY = "Currency"
+    DATE_AND_TIME = "DateAndTime.DateAndTime"
+    DATE_ONLY = "DateAndTime.DateOnly"
+    DECIMAL = "Decimal"
+    ENUM = "Enum"
+    FP = "FP"
+    LOOKUP_SIMPLE = "Lookup.Simple"
+    MULTIPLE = "Multiple"
+    MULTI_SELECT_OPTION_SET = "MultiSelectOptionSet"
+    OBJECT = "Object"
+    OPTION_SET = "OptionSet"
+    SINGLE_LINE_EMAIL = "SingleLine.Email"
+    SINGLE_LINE_PHONE = "SingleLine.Phone"
+    SINGLE_LINE_TEXT = "SingleLine.Text"
+    SINGLE_LINE_TEXT_AREA = "SingleLine.TextArea"
+    SINGLE_LINE_TICKER = "SingleLine.Ticker"
+    SINGLE_LINE_URL = "SingleLine.URL"
+    TWO_OPTIONS = "TwoOptions"
+    WHOLE_NONE = "Whole.None"
+
+
+UNSUPPORTED_TYPE_VALUES = {
+    "Lookup.Customer",
+    "Lookup.Owner",
+    "Lookup.PartyList",
+    "Lookup.Regarding",
+    "Status Reason",
+    "Status",
+    "Whole.Duration",
+    "Whole.Language",
+    "Whole.TimeZone",
+}