prizmkit 1.1.100 → 1.1.101

package/bundled/dev-pipeline/prizmkit_runtime/config.py

@@ -0,0 +1,410 @@
+"""Runtime configuration and environment resolution primitives."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import RuntimePaths
+
+
+@dataclass(frozen=True)
+class RuntimeEnvironment:
+    """Inputs that influence runtime configuration resolution."""
+
+    env_file: Path
+    config_file: Path
+    manifest_file: Path
+    installed_platform_markers: tuple[Path, ...]
+    path_entries: tuple[Path, ...]
+    sources: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class AIClientResolution:
+    """Resolved AI CLI command plus source and precedence metadata."""
+
+    command: str | None
+    platform: str | None
+    source: str
+    precedence: tuple[str, ...]
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class EffortValidationResult:
+    """Platform-aware validation result for PRIZMKIT_EFFORT."""
+
+    effort: str | None
+    platform: str | None
+    valid: bool
+    supported_values: tuple[str, ...]
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    """Cohesive runtime configuration boundary for behavior porting."""
+
+    paths: RuntimePaths
+    environment: RuntimeEnvironment
+    ai_client: AIClientResolution
+    max_retries: int
+    heartbeat_interval_seconds: int
+    heartbeat_timeout_seconds: int
+    model: str | None
+    effort: str | None
+    effort_validation: EffortValidationResult
+    runtime_mode: str = "python-runtime-canonical"
+
+
+AI_CLIENT_PRECEDENCE = (
+    "AI_CLI",
+    ".prizmkit/config.json:ai_cli",
+    ".prizmkit/manifest.json:platform",
+    ".prizmkit/config.json:platform",
+    "CODEBUDDY_CLI",
+    "installed-platform-markers",
+    "PATH:claude",
+    "PATH:cbc",
+    "PATH:codex",
+)
+
+_EFFORT_VALUES_BY_PLATFORM = {
+    "claude": ("low", "medium", "high", "xhigh", "max"),
+    "codex": ("low", "medium", "high", "xhigh"),
+    "codebuddy": ("low", "medium", "high", "xhigh"),
+}
+
+
+class RuntimeConfigError(ValueError):
+    """Raised when runtime configuration cannot be represented safely."""
+
+
+def load_env_file(path: Path, base_env: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Load a simple shell-style .env file without overriding base values.
+
+    This preserves the historical environment-file contract intentionally: comments, blank lines,
+    ``KEY=VALUE``, and one layer of single/double quotes are supported. Existing
+    keys in ``base_env`` win over file values.
+    """
+    merged = dict(base_env or {})
+    if not path.is_file():
+        return merged
+
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return merged
+
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        line = line.split("#", 1)[0].strip()
+        if not line or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if not key or not (key[0].isalpha() or key[0] == "_"):
+            continue
+        if not all(char.isalnum() or char == "_" for char in key):
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+            value = value[1:-1]
+        if key not in merged:
+            merged[key] = value
+    return merged
+
+
+def _path_entries(env: Mapping[str, str]) -> tuple[Path, ...]:
+    raw_path = env.get("PATH", "")
+    return tuple(Path(item) for item in raw_path.split(os.pathsep) if item)
+
+
+def _int_from_env(env: Mapping[str, str], name: str, default: int) -> int:
+    raw_value = env.get(name)
+    if raw_value is None or raw_value.strip() == "":
+        return default
+    try:
+        return int(raw_value)
+    except ValueError:
+        return default
+
+
+def _read_json_value(path: Path, key: str) -> str | None:
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    value = data.get(key)
+    return value if isinstance(value, str) and value.strip() else None
+
+
+def _normalize_platform(platform: str | None) -> str:
+    return (platform or "").strip().lower()
+
+
+def _cli_names_for_platform(platform: str | None) -> tuple[str, ...]:
+    normalized = _normalize_platform(platform)
+    if normalized == "codex":
+        return ("codex",)
+    if normalized == "claude":
+        return ("claude",)
+    if normalized == "codebuddy":
+        return ("cbc",)
+    if normalized == "both":
+        return ("claude", "cbc")
+    if normalized == "all":
+        return ("codex", "claude", "cbc")
+    return ()
+
+
+def _known_platform_from_cli(cli_command: str | None) -> str | None:
+    if not cli_command:
+        return None
+    token = cli_command.split()[0].strip("'\"")
+    name = Path(token).name.lower()
+    if "claude" in name:
+        return "claude"
+    if "codex" in name:
+        return "codex"
+    if "cbc" in name or "codebuddy" in name:
+        return "codebuddy"
+    return None
+
+
+def _concrete_platform(platform: str | None) -> str | None:
+    normalized = _normalize_platform(platform)
+    return normalized if normalized in {"claude", "codebuddy", "codex"} else None
+
+
+def _resolve_cli_name(cli_name: str, env: Mapping[str, str]) -> str | None:
+    if cli_name == "cbc" and env.get("CODEBUDDY_CLI"):
+        return env["CODEBUDDY_CLI"]
+    return cli_name if shutil.which(cli_name, path=env.get("PATH", "")) else None
+
+
+def _cli_for_platform(platform: str | None, env: Mapping[str, str]) -> str | None:
+    for cli_name in _cli_names_for_platform(platform):
+        resolved = _resolve_cli_name(cli_name, env)
+        if resolved:
+            return resolved
+    return None
+
+
+def _expected_cli_text(platform: str | None) -> str:
+    return ", ".join(_cli_names_for_platform(platform))
+
+
+def _installed_platform_cli(
+    paths: RuntimePaths,
+    env: Mapping[str, str],
+) -> tuple[str | None, str | None]:
+    if (
+        (paths.project_root / ".codex" / "agents" / "prizm-dev-team-dev.toml").is_file()
+        or (paths.project_root / ".agents" / "skills" / "prizm-kit" / "SKILL.md").is_file()
+    ):
+        resolved = _resolve_cli_name("codex", env)
+        if resolved:
+            return resolved, "installed-platform:codex"
+    if (paths.project_root / ".claude" / "commands" / "prizm-kit.md").is_file():
+        resolved = _resolve_cli_name("claude", env)
+        if resolved:
+            return resolved, "installed-platform:claude"
+    if (
+        (paths.project_root / ".codebuddy" / "agents" / "prizm-dev-team-dev.md").is_file()
+        or (paths.project_root / ".codebuddy" / "skills" / "prizm-kit" / "SKILL.md").is_file()
+    ):
+        resolved = _resolve_cli_name("cbc", env)
+        if resolved:
+            return resolved, "installed-platform:codebuddy"
+    return None, None
+
+
+def _project_platform_for_cli(
+    cli_command: str | None,
+    env: Mapping[str, str],
+    manifest_platform: str | None,
+    config_platform: str | None,
+) -> str | None:
+    return (
+        _known_platform_from_cli(cli_command)
+        or _concrete_platform(env.get("PRIZMKIT_PLATFORM"))
+        or _concrete_platform(manifest_platform)
+        or _concrete_platform(config_platform)
+        or ("codebuddy" if cli_command else None)
+    )
+
+
+def resolve_ai_client(
+    paths: RuntimePaths,
+    env: Mapping[str, str] | None = None,
+) -> AIClientResolution:
+    """Resolve the configured AI CLI using runtime precedence."""
+    runtime_env = dict(os.environ if env is None else env)
+    runtime_env = load_env_file(paths.prizmkit_dir / ".env", runtime_env)
+    return _resolve_ai_client(paths, runtime_env)
+
+
+def _resolve_ai_client(paths: RuntimePaths, env: Mapping[str, str]) -> AIClientResolution:
+    config_ai_cli = _read_json_value(paths.prizmkit_dir / "config.json", "ai_cli")
+    config_platform = _read_json_value(paths.prizmkit_dir / "config.json", "platform")
+    manifest_platform = _read_json_value(paths.prizmkit_dir / "manifest.json", "platform")
+
+    explicit_command = env.get("AI_CLI")
+    if explicit_command:
+        return AIClientResolution(
+            command=explicit_command,
+            platform=_project_platform_for_cli(explicit_command, env, manifest_platform, config_platform),
+            source="environment:AI_CLI",
+            precedence=AI_CLIENT_PRECEDENCE,
+        )
+
+    if config_ai_cli:
+        return AIClientResolution(
+            command=config_ai_cli,
+            platform=_project_platform_for_cli(config_ai_cli, env, manifest_platform, config_platform),
+            source="prizmkit-config:ai_cli",
+            precedence=AI_CLIENT_PRECEDENCE,
+        )
+
+    for platform, source, configured_label in (
+        (manifest_platform, "prizmkit-manifest:platform", "Installed PrizmKit platform"),
+        (config_platform, "prizmkit-config:platform", "Configured PrizmKit platform"),
+    ):
+        resolved = _cli_for_platform(platform, env)
+        if resolved:
+            return AIClientResolution(
+                command=resolved,
+                platform=_project_platform_for_cli(resolved, env, manifest_platform, config_platform),
+                source=source,
+                precedence=AI_CLIENT_PRECEDENCE,
+            )
+        if _cli_names_for_platform(platform):
+            return AIClientResolution(
+                command=None,
+                platform=_concrete_platform(platform),
+                source=f"unresolved:{source}",
+                precedence=AI_CLIENT_PRECEDENCE,
+                notes=(
+                    f"{configured_label} '{platform}' requires one of: "
+                    f"{_expected_cli_text(platform)}. Install it or set AI_CLI.",
+                ),
+            )
+
+    if env.get("CODEBUDDY_CLI"):
+        command = env["CODEBUDDY_CLI"]
+        return AIClientResolution(
+            command=command,
+            platform=_project_platform_for_cli(command, env, manifest_platform, config_platform),
+            source="environment:CODEBUDDY_CLI",
+            precedence=AI_CLIENT_PRECEDENCE,
+        )
+
+    installed_command, installed_source = _installed_platform_cli(paths, env)
+    if installed_command:
+        return AIClientResolution(
+            command=installed_command,
+            platform=_project_platform_for_cli(installed_command, env, manifest_platform, config_platform),
+            source=installed_source or "installed-platform-markers",
+            precedence=AI_CLIENT_PRECEDENCE,
+        )
+
+    for candidate in ("claude", "cbc", "codex"):
+        resolved = _resolve_cli_name(candidate, env)
+        if resolved:
+            return AIClientResolution(
+                command=resolved,
+                platform=_project_platform_for_cli(resolved, env, manifest_platform, config_platform),
+                source=f"PATH:{candidate}",
+                precedence=AI_CLIENT_PRECEDENCE,
+            )
+
+    return AIClientResolution(
+        command=None,
+        platform=None,
+        source="unresolved",
+        precedence=AI_CLIENT_PRECEDENCE,
+        notes=("No supported AI CLI command was found in the provided environment.",),
+    )
+
+
+def supported_effort_values(platform: str | None) -> tuple[str, ...]:
+    """Return supported PRIZMKIT_EFFORT values for the detected platform."""
+    return _EFFORT_VALUES_BY_PLATFORM.get(
+        _concrete_platform(platform) or "codebuddy",
+        _EFFORT_VALUES_BY_PLATFORM["codebuddy"],
+    )
+
+
+def validate_effort(effort: str | None, platform: str | None) -> EffortValidationResult:
+    """Validate PRIZMKIT_EFFORT without exiting the process."""
+    supported = supported_effort_values(platform)
+    if effort is None or str(effort).strip() == "":
+        return EffortValidationResult(
+            effort=None,
+            platform=_concrete_platform(platform),
+            valid=True,
+            supported_values=supported,
+        )
+    normalized_effort = str(effort).strip()
+    valid = normalized_effort in supported
+    message = ""
+    if not valid:
+        label = {
+            "claude": "Claude Code",
+            "codex": "Codex",
+            "codebuddy": "CodeBuddy",
+        }.get(_concrete_platform(platform) or "codebuddy", "CodeBuddy")
+        message = (
+            f"PRIZMKIT_EFFORT='{normalized_effort}' is not supported by the detected CLI "
+            f"({label}). Supported values for {label}: {', '.join(supported)}"
+        )
+    return EffortValidationResult(
+        effort=normalized_effort,
+        platform=_concrete_platform(platform),
+        valid=valid,
+        supported_values=supported,
+        message=message,
+    )
+
+
+def load_runtime_config(paths: RuntimePaths, env: Mapping[str, str] | None = None) -> RuntimeConfig:
+    """Load standard-library runtime configuration with canonical precedence."""
+    provided_env = dict(os.environ if env is None else env)
+    runtime_env = load_env_file(paths.prizmkit_dir / ".env", provided_env)
+    ai_client = _resolve_ai_client(paths, runtime_env)
+    effort = runtime_env.get("PRIZMKIT_EFFORT")
+    effort_validation = validate_effort(effort, ai_client.platform)
+    environment = RuntimeEnvironment(
+        env_file=paths.prizmkit_dir / ".env",
+        config_file=paths.prizmkit_dir / "config.json",
+        manifest_file=paths.prizmkit_dir / "manifest.json",
+        installed_platform_markers=(
+            paths.project_root / ".codebuddy",
+            paths.project_root / ".claude",
+            paths.project_root / ".codex",
+        ),
+        path_entries=_path_entries(runtime_env),
+        sources=("environment", "prizmkit-env", "prizmkit-config", "installed-platform-markers", "PATH"),
+    )
+
+    return RuntimeConfig(
+        paths=paths,
+        environment=environment,
+        ai_client=ai_client,
+        max_retries=_int_from_env(runtime_env, "MAX_RETRIES", 3),
+        heartbeat_interval_seconds=_int_from_env(runtime_env, "HEARTBEAT_INTERVAL", _int_from_env(runtime_env, "HEARTBEAT_INTERVAL_SECONDS", 30)),
+        heartbeat_timeout_seconds=_int_from_env(runtime_env, "HEARTBEAT_STALE_THRESHOLD", _int_from_env(runtime_env, "HEARTBEAT_TIMEOUT_SECONDS", 600)),
+        model=runtime_env.get("MODEL"),
+        effort=effort,
+        effort_validation=effort_validation,
+    )