pcf-toolkit 0.2.5__py3-none-any.whl

pcf_toolkit/proxy/config.py

@@ -0,0 +1,310 @@
+"""Proxy configuration schema and helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+DEFAULT_CONFIG_FILENAMES = ("pcf-proxy.yaml", "pcf-proxy.yml", "pcf-proxy.json")
+
+
+class ProxyEndpoint(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    host: str = Field(default="127.0.0.1")
+    port: int = Field(default=8080)
+
+
+class HttpServerConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    host: str = Field(default="127.0.0.1")
+    port: int = Field(default=8082)
+
+
+class BundleConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    dist_path: str = Field(
+        default="out/controls/{PCF_NAME}",
+        description="Relative path to the built control output.",
+    )
+
+
+class BrowserConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prefer: str | None = Field(default="chrome", description="Preferred browser: chrome or edge.")
+    path: Path | None = Field(default=None, description="Explicit browser executable path.")
+
+
+class MitmproxyConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    path: Path | None = Field(default=None, description="Explicit mitmproxy/mitmdump executable path.")
+
+
+class EnvironmentConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="Environment name from PAC CLI.")
+    url: str = Field(description="Environment URL.")
+    active: bool = Field(default=False, description="Active PAC environment.")
+
+
+class ProxyConfig(BaseModel):
+    """Configuration for the PCF proxy workflow."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    project_root: str | None = Field(
+        default=None,
+        description="Project root path for global configs.",
+    )
+    crm_url: str | None = Field(default=None, description="Base CRM URL, e.g. https://yourorg.crm.dynamics.com/")
+    expected_path: str = Field(
+        default="/webresources/{PCF_NAME}/",
+        description="Request path template that matches the PCF webresource base.",
+    )
+    proxy: ProxyEndpoint = Field(default_factory=ProxyEndpoint)
+    http_server: HttpServerConfig = Field(default_factory=HttpServerConfig)
+    bundle: BundleConfig = Field(default_factory=BundleConfig)
+    browser: BrowserConfig = Field(default_factory=BrowserConfig)
+    mitmproxy: MitmproxyConfig = Field(default_factory=MitmproxyConfig)
+    environments: list[EnvironmentConfig] | None = Field(
+        default=None,
+        description="Known CRM environments for selection.",
+    )
+    open_browser: bool = Field(default=True)
+    auto_install: bool = Field(default=True)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _migrate_flat_keys(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        data = dict(data)
+        data.pop("$schema", None)
+        if "proxy" in data or "http_server" in data or "bundle" in data:
+            return data
+        migrated = dict(data)
+        proxy = {"host": migrated.pop("proxy_host", None), "port": migrated.pop("proxy_port", None)}
+        http_server = {
+            "host": migrated.pop("http_host", None),
+            "port": migrated.pop("http_port", None),
+        }
+        bundle = {"dist_path": migrated.pop("dist_path", None)}
+        browser = {
+            "prefer": migrated.pop("browser", None),
+            "path": migrated.pop("browser_path", None),
+        }
+        mitmproxy = {"path": migrated.pop("mitmproxy_path", None)}
+        migrated["proxy"] = {k: v for k, v in proxy.items() if v is not None}
+        migrated["http_server"] = {k: v for k, v in http_server.items() if v is not None}
+        migrated["bundle"] = {k: v for k, v in bundle.items() if v is not None}
+        migrated["browser"] = {k: v for k, v in browser.items() if v is not None}
+        migrated["mitmproxy"] = {k: v for k, v in mitmproxy.items() if v is not None}
+        return migrated
+
+
+class LoadedConfig(BaseModel):
+    """Configuration plus metadata about where it came from."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    path: Path
+    config: ProxyConfig
+
+
+def global_config_path() -> Path:
+    """Returns the path to the global proxy config file.
+
+    Returns:
+      Path to ~/.pcf-toolkit/pcf-proxy.yaml.
+    """
+    return Path.home() / ".pcf-toolkit" / "pcf-proxy.yaml"
+
+
+def default_config_path(cwd: Path | None = None) -> Path:
+    """Returns the default config path for the current directory.
+
+    Searches for existing config files first, otherwise returns the default name.
+
+    Args:
+      cwd: Current working directory. If None, uses Path.cwd().
+
+    Returns:
+      Path to the config file (existing or default).
+    """
+    root = cwd or Path.cwd()
+    for filename in DEFAULT_CONFIG_FILENAMES:
+        candidate = root / filename
+        if candidate.exists():
+            return candidate
+    return root / DEFAULT_CONFIG_FILENAMES[0]
+
+
+def load_config(path: Path | None = None, cwd: Path | None = None) -> LoadedConfig:
+    """Loads proxy configuration from a file.
+
+    Tries the specified path, then local config, then global config.
+
+    Args:
+      path: Explicit config file path. If None, searches for local config.
+      cwd: Current working directory for local config search.
+
+    Returns:
+      LoadedConfig instance with config and path metadata.
+
+    Raises:
+      FileNotFoundError: If no config file can be found.
+    """
+    resolved_path = path or default_config_path(cwd)
+    if not resolved_path.exists():
+        global_path = global_config_path()
+        if global_path.exists():
+            resolved_path = global_path
+    if not resolved_path.exists():
+        raise FileNotFoundError(f"Config file not found: {resolved_path}")
+    content = resolved_path.read_text(encoding="utf-8").strip()
+    data: dict[str, Any]
+    if not content:
+        data = {}
+    elif resolved_path.suffix.lower() == ".json":
+        data = _load_json(content)
+    else:
+        data = _load_yaml(content)
+    return LoadedConfig(path=resolved_path, config=ProxyConfig.model_validate(data))
+
+
+def write_default_config(
+    path: Path,
+    overwrite: bool = False,
+    header_comment: list[str] | None = None,
+) -> Path:
+    """Writes a default proxy configuration file.
+
+    Args:
+      path: File path to write the config to.
+      overwrite: If True, overwrites existing file.
+      header_comment: Optional list of comment lines to include in header.
+
+    Returns:
+      The path where the config was written.
+
+    Raises:
+      FileExistsError: If file exists and overwrite is False.
+    """
+    if path.exists() and not overwrite:
+        raise FileExistsError(f"Config file already exists: {path}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    config = ProxyConfig(
+        crm_url="https://yourorg.crm.dynamics.com/",
+        expected_path="/webresources/{PCF_NAME}/",
+        proxy=ProxyEndpoint(host="127.0.0.1", port=8080),
+        http_server=HttpServerConfig(host="127.0.0.1", port=8082),
+        bundle=BundleConfig(dist_path="out/controls/{PCF_NAME}"),
+        browser=BrowserConfig(prefer="chrome"),
+        mitmproxy=MitmproxyConfig(path=None),
+        open_browser=True,
+        auto_install=True,
+    )
+    schema_url = (
+        "https://raw.githubusercontent.com/vectorfy-co/pcf-toolkit/refs/heads/main/schemas/pcf-proxy.schema.json"
+    )
+    payload = config.model_dump()
+    if path.suffix.lower() == ".json":
+        if "$schema" not in payload:
+            payload = {"$schema": schema_url, **payload}
+        text = _dump_json(payload)
+    else:
+        text = _dump_yaml(payload)
+        header_lines = [f"# yaml-language-server: $schema={schema_url}"]
+        if header_comment:
+            header_lines.extend(f"# {line}" for line in header_comment if line)
+        text = "\n".join(header_lines) + "\n" + text
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def render_dist_path(config: ProxyConfig, component: str, root: Path) -> Path:
+    """Renders the dist path template with component name.
+
+    Args:
+      config: Proxy configuration containing dist_path template.
+      component: PCF component name to substitute.
+      root: Project root directory.
+
+    Returns:
+      Resolved Path object for the component's dist directory.
+    """
+    relative = config.bundle.dist_path.replace("{PCF_NAME}", component)
+    return root / relative
+
+
+def _load_json(content: str) -> dict[str, Any]:
+    """Loads JSON content into a dictionary.
+
+    Args:
+      content: JSON string to parse.
+
+    Returns:
+      Parsed dictionary data.
+    """
+    import json
+
+    return json.loads(content)
+
+
+def _load_yaml(content: str) -> dict[str, Any]:
+    """Loads YAML content into a dictionary.
+
+    Args:
+      content: YAML string to parse.
+
+    Returns:
+      Parsed dictionary data.
+
+    Raises:
+      ValueError: If content is not a mapping.
+    """
+    data = yaml.safe_load(content)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError("Config file must be a mapping")
+    return data
+
+
+def _dump_json(data: dict[str, Any]) -> str:
+    """Serializes dictionary to JSON string.
+
+    Args:
+      data: Dictionary to serialize.
+
+    Returns:
+      Formatted JSON string with newline.
+    """
+    import json
+
+    return json.dumps(data, indent=2, sort_keys=True) + "\n"
+
+
+def _dump_yaml(data: dict[str, Any]) -> str:
+    """Serializes dictionary to YAML string.
+
+    Args:
+      data: Dictionary to serialize.
+
+    Returns:
+      Formatted YAML string.
+    """
+    return yaml.safe_dump(
+        data,
+        sort_keys=False,
+        default_flow_style=False,
+        allow_unicode=False,
+    )

pcf_toolkit/proxy/doctor.py

@@ -0,0 +1,279 @@
+"""Doctor checks for the proxy workflow."""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from pcf_toolkit.proxy.browser import find_browser_binary
+from pcf_toolkit.proxy.config import ProxyConfig, render_dist_path
+from pcf_toolkit.proxy.mitm import find_mitmproxy
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: str
+    message: str
+    fix: str | None = None
+
+
+def run_doctor(
+    config: ProxyConfig | None,
+    config_path: Path | None,
+    component: str | None,
+    project_root: Path,
+) -> list[CheckResult]:
+    """Runs diagnostic checks for proxy workflow prerequisites.
+
+    Args:
+      config: Proxy configuration (optional).
+      config_path: Path to config file (optional).
+      component: Component name to validate (optional).
+      project_root: Project root directory.
+
+    Returns:
+      List of CheckResult objects describing check outcomes.
+    """
+    results: list[CheckResult] = []
+
+    if config_path and not config_path.exists():
+        results.append(
+            CheckResult(
+                name="config",
+                status="fail",
+                message=f"Config not found at {config_path}",
+                fix="Run 'pcf-toolkit proxy init' to create one.",
+            )
+        )
+    elif config_path:
+        results.append(
+            CheckResult(
+                name="config",
+                status="ok",
+                message=f"Loaded config from {config_path}",
+            )
+        )
+
+    if config:
+        if not config.crm_url or "yourorg" in config.crm_url:
+            results.append(
+                CheckResult(
+                    name="crm_url",
+                    status="warn",
+                    message="CRM URL is missing or still a placeholder.",
+                    fix="Set 'crm_url' in your proxy config.",
+                )
+            )
+        else:
+            results.append(
+                CheckResult(
+                    name="crm_url",
+                    status="ok",
+                    message="CRM URL configured.",
+                )
+            )
+
+        results.extend(_check_ports(config))
+        results.extend(_check_mitmproxy(config))
+        results.extend(_check_certificates())
+        results.extend(_check_browser(config))
+
+        if component:
+            results.extend(_check_dist_path(config, component, project_root))
+    else:
+        results.append(
+            CheckResult(
+                name="config",
+                status="fail",
+                message="Config was not loaded.",
+                fix="Run 'pcf-toolkit proxy init' and set required values.",
+            )
+        )
+
+    return results
+
+
+def _check_ports(config: ProxyConfig) -> list[CheckResult]:
+    """Checks if proxy and HTTP server ports are available.
+
+    Args:
+      config: Proxy configuration.
+
+    Returns:
+      List of CheckResult objects for port availability.
+    """
+    results = []
+    for label, host, port in (
+        ("proxy_port", config.proxy.host, config.proxy.port),
+        ("http_port", config.http_server.host, config.http_server.port),
+    ):
+        if _port_available(host, port):
+            results.append(
+                CheckResult(
+                    name=label,
+                    status="ok",
+                    message=f"{host}:{port} is available.",
+                )
+            )
+        else:
+            results.append(
+                CheckResult(
+                    name=label,
+                    status="fail",
+                    message=f"{host}:{port} is already in use.",
+                    fix="Change the port in config or stop the process using it.",
+                )
+            )
+    return results
+
+
+def _check_mitmproxy(config: ProxyConfig) -> list[CheckResult]:
+    """Checks if mitmproxy is available.
+
+    Args:
+      config: Proxy configuration.
+
+    Returns:
+      List of CheckResult objects for mitmproxy availability.
+    """
+    binary = find_mitmproxy(config.mitmproxy.path)
+    if binary:
+        return [
+            CheckResult(
+                name="mitmproxy",
+                status="ok",
+                message=f"mitmproxy available at {binary}",
+            )
+        ]
+    return [
+        CheckResult(
+            name="mitmproxy",
+            status="fail",
+            message="mitmproxy not found.",
+            fix="Install mitmproxy or run 'pcf-toolkit proxy doctor --fix'.",
+        )
+    ]
+
+
+def _check_certificates() -> list[CheckResult]:
+    """Checks if mitmproxy CA certificate is installed.
+
+    Returns:
+      List of CheckResult objects for certificate status.
+    """
+    cert_dir = Path.home() / ".mitmproxy"
+    cert_file = cert_dir / "mitmproxy-ca-cert.pem"
+    if cert_file.exists():
+        return [
+            CheckResult(
+                name="mitmproxy_cert",
+                status="ok",
+                message=f"mitmproxy CA cert found at {cert_file}",
+            )
+        ]
+    return [
+        CheckResult(
+            name="mitmproxy_cert",
+            status="warn",
+            message="mitmproxy CA cert not found.",
+            fix=_cert_fix_instructions(cert_dir),
+        )
+    ]
+
+
+def _check_browser(config: ProxyConfig) -> list[CheckResult]:
+    """Checks if browser is available.
+
+    Args:
+      config: Proxy configuration.
+
+    Returns:
+      List of CheckResult objects for browser availability.
+    """
+    binary = find_browser_binary(config.browser.prefer, config.browser.path)
+    if binary:
+        return [
+            CheckResult(
+                name="browser",
+                status="ok",
+                message=f"Browser found at {binary}",
+            )
+        ]
+    return [
+        CheckResult(
+            name="browser",
+            status="warn",
+            message="Browser not found.",
+            fix="Set 'browser.path' in config or install Chrome/Edge.",
+        )
+    ]
+
+
+def _check_dist_path(config: ProxyConfig, component: str, project_root: Path) -> list[CheckResult]:
+    """Checks if component dist path exists.
+
+    Args:
+      config: Proxy configuration.
+      component: Component name.
+      project_root: Project root directory.
+
+    Returns:
+      List of CheckResult objects for dist path status.
+    """
+    dist_path = render_dist_path(config, component, project_root)
+    if dist_path.exists():
+        return [
+            CheckResult(
+                name="dist_path",
+                status="ok",
+                message=f"Dist path exists at {dist_path}",
+            )
+        ]
+    return [
+        CheckResult(
+            name="dist_path",
+            status="warn",
+            message=f"Dist path missing: {dist_path}",
+            fix="Run 'npm run build' or adjust 'bundle.dist_path' in config.",
+        )
+    ]
+
+
+def _port_available(host: str, port: int) -> bool:
+    """Checks if a port is available for binding.
+
+    Args:
+      host: Hostname to bind to.
+      port: Port number to check.
+
+    Returns:
+      True if port is available, False otherwise.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((host, port))
+            return True
+        except OSError:
+            return False
+
+
+def _cert_fix_instructions(cert_dir: Path) -> str:
+    """Generates platform-specific certificate installation instructions.
+
+    Args:
+      cert_dir: Directory containing mitmproxy certificate.
+
+    Returns:
+      Command string for installing the certificate.
+    """
+    cert_path = cert_dir / "mitmproxy-ca-cert.pem"
+    if os.name == "nt":
+        return f"Run: certutil -addstore -f Root {cert_path} (elevated)"
+    if sys.platform == "darwin":
+        return f"Run: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain {cert_path}"
+    return f"Run: sudo cp {cert_path} /usr/local/share/ca-certificates/ && sudo update-ca-certificates"