norn-cli 0.7.1__py3-none-any.whl

norf_harness/config.py

@@ -0,0 +1,398 @@
+"""Configuration loading, merging, and validation."""
+
+from __future__ import annotations
+
+import copy
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class ConfigError(ValueError):
+    """Raised when harness configuration is invalid."""
+
+
+@dataclass(frozen=True)
+class QualityGateConfig:
+    critical: int
+    high: int
+    medium: int
+    low: int
+
+
+@dataclass(frozen=True)
+class LimitsConfig:
+    max_total_rounds: int
+    max_planning_retries: int
+    max_implementation_rounds: int
+    max_final_replans: int
+    max_provider_retries: int
+    role_timeout_seconds: int
+    test_timeout_seconds: int
+    e2e_timeout_seconds: int
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    name: str
+    adapter: str
+    command: str
+    auth: str
+    args: tuple[str, ...] = ()
+    output: str = "json"
+
+
+@dataclass(frozen=True)
+class ModelCandidate:
+    provider: str
+    model: str
+    effort: str
+    model_id: str = ""
+
+    @property
+    def resolved_model(self) -> str:
+        """Provider-facing model identifier, preserving a stable logical alias."""
+        return self.model_id or self.model
+
+
+@dataclass(frozen=True)
+class ProfileConfig:
+    name: str
+    candidates: tuple[ModelCandidate, ...]
+
+
+@dataclass(frozen=True)
+class GateCommandConfig:
+    name: str
+    kind: str
+    command: tuple[str, ...]
+    timeout_seconds: int | None = None
+
+
+@dataclass(frozen=True)
+class ProjectGatesConfig:
+    enabled: bool
+    auto_detect: bool
+    commands: tuple[GateCommandConfig, ...]
+
+
+@dataclass(frozen=True)
+class GitConfig:
+    worktree: bool
+    auto_commit: bool
+    publish: bool
+
+
+@dataclass(frozen=True)
+class HarnessConfig:
+    project_root: Path
+    quality_gate: QualityGateConfig
+    limits: LimitsConfig
+    runs_dir: Path
+    providers: Mapping[str, ProviderConfig]
+    profiles: Mapping[str, ProfileConfig]
+    roles: Mapping[str, str]
+    project_gates: ProjectGatesConfig
+    git: GitConfig
+    e2e_enabled: bool
+    e2e_required_for_ui_changes: bool
+    e2e_require_all_testers: bool
+    raw: Mapping[str, Any]
+    sources: tuple[Path, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return copy.deepcopy(dict(self.raw))
+
+
+def default_config_path() -> Path:
+    return Path(str(files("norf_harness").joinpath("resources/default.yaml")))
+
+
+def user_config_path() -> Path:
+    overridden = os.environ.get("NORN_USER_CONFIG") or os.environ.get("NORF_HARNESS_USER_CONFIG")
+    if overridden:
+        return Path(overridden).expanduser()
+    canonical = Path.home() / ".config" / "norn" / "config.yaml"
+    legacy = Path.home() / ".config" / "norf-harness" / "config.yaml"
+    if not canonical.is_file() and legacy.is_file():
+        return legacy
+    return canonical
+
+
+def project_config_path(project_root: Path) -> Path:
+    return project_root / ".norf" / "harness.yaml"
+
+
+def load_config(
+    project_root: Path | str,
+    *,
+    config_path: Path | str | None = None,
+    overrides: Mapping[str, Any] | None = None,
+) -> HarnessConfig:
+    """Load defaults < user < project/explicit < CLI overrides."""
+
+    root = Path(project_root).expanduser().resolve()
+    sources: list[Path] = []
+
+    default_path = default_config_path()
+    raw = _load_yaml(default_path, required=True)
+    sources.append(default_path)
+
+    user_path = user_config_path()
+    if user_path.is_file():
+        raw = _deep_merge(raw, _load_yaml(user_path, required=True))
+        sources.append(user_path)
+
+    selected_project_path = (
+        Path(config_path).expanduser().resolve()
+        if config_path is not None
+        else project_config_path(root)
+    )
+    if selected_project_path.is_file():
+        raw = _deep_merge(raw, _load_yaml(selected_project_path, required=True))
+        sources.append(selected_project_path)
+    elif config_path is not None:
+        raise ConfigError(f"Config file does not exist: {selected_project_path}")
+
+    for dotted_key, value in (overrides or {}).items():
+        _set_dotted(raw, dotted_key, value)
+
+    return _validate(root, raw, tuple(sources))
+
+
+def _load_yaml(path: Path, *, required: bool) -> dict[str, Any]:
+    if not path.is_file():
+        if required:
+            raise ConfigError(f"Config file does not exist: {path}")
+        return {}
+    try:
+        value = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        raise ConfigError(f"Failed to load config {path}: {exc}") from exc
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"Config root must be a mapping: {path}")
+    return value
+
+
+def _deep_merge(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    result = copy.deepcopy(dict(base))
+    for key, value in override.items():
+        if isinstance(result.get(key), dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+    return result
+
+
+def _set_dotted(target: dict[str, Any], dotted_key: str, value: Any) -> None:
+    parts = dotted_key.split(".")
+    if not parts or any(not part for part in parts):
+        raise ConfigError(f"Invalid override key: {dotted_key!r}")
+    cursor = target
+    for part in parts[:-1]:
+        child = cursor.setdefault(part, {})
+        if not isinstance(child, dict):
+            raise ConfigError(f"Cannot override nested key below {part!r}")
+        cursor = child
+    cursor[parts[-1]] = value
+
+
+def _mapping(raw: Mapping[str, Any], key: str) -> Mapping[str, Any]:
+    value = raw.get(key)
+    if not isinstance(value, dict):
+        raise ConfigError(f"{key} must be a mapping")
+    return value
+
+
+def _integer(mapping: Mapping[str, Any], key: str, *, minimum: int = 0) -> int:
+    value = mapping.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise ConfigError(f"{key} must be an integer >= {minimum}")
+    return value
+
+
+def _positive(mapping: Mapping[str, Any], key: str) -> int:
+    return _integer(mapping, key, minimum=1)
+
+
+def _boolean(mapping: Mapping[str, Any], key: str) -> bool:
+    value = mapping.get(key)
+    if not isinstance(value, bool):
+        raise ConfigError(f"{key} must be a boolean")
+    return value
+
+
+def _validate(root: Path, raw: dict[str, Any], sources: tuple[Path, ...]) -> HarnessConfig:
+    if raw.get("version") != 1:
+        raise ConfigError("version must be 1")
+
+    gate_raw = _mapping(raw, "quality_gate")
+    gate = QualityGateConfig(
+        critical=_integer(gate_raw, "critical"),
+        high=_integer(gate_raw, "high"),
+        medium=_integer(gate_raw, "medium"),
+        low=_integer(gate_raw, "low", minimum=-1),
+    )
+    if gate.low < -1:
+        raise ConfigError("quality_gate.low must be -1 (unlimited) or >= 0")
+
+    limits_raw = _mapping(raw, "limits")
+    pipeline = _mapping(limits_raw, "pipeline")
+    planning = _mapping(limits_raw, "planning")
+    implementation = _mapping(limits_raw, "implementation")
+    final_gate = _mapping(limits_raw, "final_gate")
+    provider_limits = _mapping(limits_raw, "providers")
+    timeouts = _mapping(limits_raw, "timeouts")
+    limits = LimitsConfig(
+        max_total_rounds=_positive(pipeline, "max_total_rounds"),
+        max_planning_retries=_integer(planning, "max_retries"),
+        max_implementation_rounds=_positive(implementation, "max_rounds"),
+        max_final_replans=_integer(final_gate, "max_replans"),
+        max_provider_retries=_integer(provider_limits, "max_retries_per_call"),
+        role_timeout_seconds=_positive(timeouts, "role_seconds"),
+        test_timeout_seconds=_positive(timeouts, "test_seconds"),
+        e2e_timeout_seconds=_positive(timeouts, "e2e_seconds"),
+    )
+    if limits.max_implementation_rounds > limits.max_total_rounds:
+        raise ConfigError("implementation.max_rounds cannot exceed pipeline.max_total_rounds")
+
+    paths = _mapping(raw, "paths")
+    runs_dir_value = paths.get("runs_dir")
+    if not isinstance(runs_dir_value, str) or not runs_dir_value.strip():
+        raise ConfigError("paths.runs_dir must be a non-empty string")
+    runs_dir = Path(runs_dir_value).expanduser()
+    if not runs_dir.is_absolute():
+        runs_dir = root / runs_dir
+    runs_dir = runs_dir.resolve()
+
+    providers_raw = _mapping(raw, "providers")
+    providers: dict[str, ProviderConfig] = {}
+    for name, value in providers_raw.items():
+        if not isinstance(name, str) or not isinstance(value, dict):
+            raise ConfigError("providers entries must be named mappings")
+        adapter = value.get("adapter")
+        command = value.get("command")
+        auth = value.get("auth")
+        if not all(isinstance(item, str) and item for item in (adapter, command, auth)):
+            raise ConfigError(f"provider {name!r} requires adapter, command, and auth")
+        args = value.get("args", [])
+        output = value.get("output", "json")
+        if not isinstance(args, list) or not all(isinstance(item, str) for item in args):
+            raise ConfigError(f"provider {name!r} args must be a list of strings")
+        if output not in {"json", "jsonl", "text"}:
+            raise ConfigError(f"provider {name!r} output must be json, jsonl, or text")
+        providers[name] = ProviderConfig(name, adapter, command, auth, tuple(args), output)
+
+    profiles_raw = _mapping(raw, "profiles")
+    profiles: dict[str, ProfileConfig] = {}
+    for name, value in profiles_raw.items():
+        if not isinstance(name, str) or not isinstance(value, dict):
+            raise ConfigError("profiles entries must be named mappings")
+        candidate_values = value.get("candidates")
+        if not isinstance(candidate_values, list) or not candidate_values:
+            raise ConfigError(f"profile {name!r} requires at least one candidate")
+        candidates: list[ModelCandidate] = []
+        for candidate in candidate_values:
+            if not isinstance(candidate, dict):
+                raise ConfigError(f"profile {name!r} candidates must be mappings")
+            provider = candidate.get("provider")
+            model = candidate.get("model")
+            model_id = candidate.get("model_id", "")
+            effort = candidate.get("effort")
+            if provider not in providers:
+                raise ConfigError(f"profile {name!r} references unknown provider {provider!r}")
+            if not isinstance(model, str) or not model:
+                raise ConfigError(f"profile {name!r} candidate model must be non-empty")
+            if not isinstance(model_id, str):
+                raise ConfigError(f"profile {name!r} candidate model_id must be a string")
+            if effort not in {"low", "medium", "high", "xhigh", "max"}:
+                raise ConfigError(f"profile {name!r} has invalid effort {effort!r}")
+            candidates.append(ModelCandidate(provider, model, effort, model_id))
+        profiles[name] = ProfileConfig(name, tuple(candidates))
+
+    roles_raw = _mapping(raw, "roles")
+    roles: dict[str, str] = {}
+    required_roles = {
+        "orchestrator",
+        "planner",
+        "plan_reviewer",
+        "implementer",
+        "spec_tester",
+        "clean_tester",
+        "security_tester",
+        "chaos_tester",
+        "triage",
+        "final_gate",
+    }
+    for role, value in roles_raw.items():
+        if not isinstance(role, str) or not isinstance(value, dict):
+            raise ConfigError("roles entries must be named mappings")
+        profile = value.get("profile")
+        if profile not in profiles:
+            raise ConfigError(f"role {role!r} references unknown profile {profile!r}")
+        roles[role] = profile
+    missing_roles = sorted(required_roles - roles.keys())
+    if missing_roles:
+        raise ConfigError(f"missing required roles: {', '.join(missing_roles)}")
+
+    gates_raw = _mapping(raw, "gates")
+    gate_commands_raw = gates_raw.get("commands", [])
+    if not isinstance(gate_commands_raw, list):
+        raise ConfigError("gates.commands must be a list")
+    gate_commands: list[GateCommandConfig] = []
+    for index, value in enumerate(gate_commands_raw):
+        if not isinstance(value, dict):
+            raise ConfigError(f"gates.commands[{index}] must be a mapping")
+        name = value.get("name")
+        kind = value.get("kind")
+        command = value.get("command")
+        timeout = value.get("timeout_seconds")
+        if not isinstance(name, str) or not name.strip():
+            raise ConfigError(f"gates.commands[{index}].name must be non-empty")
+        if kind not in {"test", "lint"}:
+            raise ConfigError(f"gates.commands[{index}].kind must be test or lint")
+        if (
+            not isinstance(command, list)
+            or not command
+            or not all(isinstance(item, str) and item for item in command)
+        ):
+            raise ConfigError(f"gates.commands[{index}].command must be a non-empty argv list")
+        if timeout is not None and (
+            isinstance(timeout, bool) or not isinstance(timeout, int) or timeout < 1
+        ):
+            raise ConfigError(f"gates.commands[{index}].timeout_seconds must be >= 1")
+        gate_commands.append(GateCommandConfig(name, kind, tuple(command), timeout))
+
+    e2e = _mapping(raw, "e2e")
+    git = _mapping(raw, "git")
+    return HarnessConfig(
+        project_root=root,
+        quality_gate=gate,
+        limits=limits,
+        runs_dir=runs_dir,
+        providers=providers,
+        profiles=profiles,
+        roles=roles,
+        project_gates=ProjectGatesConfig(
+            enabled=_boolean(gates_raw, "enabled"),
+            auto_detect=_boolean(gates_raw, "auto_detect"),
+            commands=tuple(gate_commands),
+        ),
+        git=GitConfig(
+            worktree=_boolean(git, "worktree"),
+            auto_commit=_boolean(git, "auto_commit"),
+            publish=_boolean(git, "publish"),
+        ),
+        e2e_enabled=_boolean(e2e, "enabled"),
+        e2e_required_for_ui_changes=_boolean(e2e, "required_for_ui_changes"),
+        e2e_require_all_testers=_boolean(e2e, "require_all_testers"),
+        raw=copy.deepcopy(raw),
+        sources=sources,
+    )

norf_harness/doctor.py

@@ -0,0 +1,103 @@
+"""Read-only local environment diagnostics."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .config import HarnessConfig, project_config_path
+from .providers import default_registry
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    status: str
+    detail: str
+
+
+def run_doctor(config: HarnessConfig) -> list[Check]:
+    checks: list[Check] = []
+    checks.append(
+        Check(
+            "python",
+            "PASS" if sys.version_info >= (3, 12) else "FAIL",
+            sys.version.split()[0],
+        )
+    )
+    checks.append(_git_check(config.project_root))
+    project_config = project_config_path(config.project_root)
+    checks.append(
+        Check(
+            "project-config",
+            "PASS" if project_config.is_file() else "WARN",
+            str(project_config) if project_config.is_file() else "using package/user defaults",
+        )
+    )
+    adapters = default_registry()
+    for name, provider in config.providers.items():
+        adapter = adapters.get(provider.adapter)
+        if adapter is None:
+            checks.append(
+                Check(
+                    f"provider:{name}",
+                    "FAIL",
+                    f"adapter not registered: {provider.adapter}",
+                )
+            )
+            continue
+        probe = adapter.probe(provider)
+        status = "PASS" if probe.compatible else ("WARN" if not probe.available else "FAIL")
+        checks.append(
+            Check(
+                f"provider:{name}",
+                status,
+                f"{probe.command} — {probe.detail}",
+            )
+        )
+    for name, profile in config.profiles.items():
+        available = [
+            candidate
+            for candidate in profile.candidates
+            if shutil.which(config.providers[candidate.provider].command)
+        ]
+        checks.append(
+            Check(
+                f"profile:{name}",
+                "PASS" if available else "FAIL",
+                (
+                    f"{available[0].provider}/{available[0].model}"
+                    f"->{available[0].resolved_model}/{available[0].effort}"
+                    if available
+                    else "no locally available provider candidate"
+                ),
+            )
+        )
+    return checks
+
+
+def checks_as_dict(checks: list[Check]) -> list[dict[str, str]]:
+    return [asdict(check) for check in checks]
+
+
+def doctor_exit_code(checks: list[Check]) -> int:
+    return 1 if any(check.status == "FAIL" for check in checks) else 0
+
+
+def _git_check(root: Path) -> Check:
+    try:
+        proc = subprocess.run(
+            ["git", "-C", str(root), "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return Check("git-repository", "FAIL", str(exc))
+    if proc.returncode != 0:
+        return Check("git-repository", "FAIL", proc.stderr.strip() or "not a git repository")
+    return Check("git-repository", "PASS", proc.stdout.strip())

norf_harness/e2e_evidence.py

@@ -0,0 +1,163 @@
+"""Validate and archive tester-produced E2E evidence."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+MAX_EVIDENCE_FILES = 20
+MAX_EVIDENCE_BYTES = 64 * 1024 * 1024
+
+
+class EvidenceError(RuntimeError):
+    """Raised when an isolated evidence directory cannot be prepared safely."""
+
+
+@dataclass(frozen=True)
+class EvidenceValidation:
+    errors: tuple[str, ...]
+    archived: tuple[str, ...]
+
+    @property
+    def valid(self) -> bool:
+        return not self.errors
+
+
+def prepare_evidence_directory(
+    workspace_root: Path, run_id: str, round_number: int, role: str
+) -> Path:
+    workspace = workspace_root.resolve(strict=True)
+    parent = workspace
+    for part in (".norf", "e2e-evidence", run_id, f"round-{round_number}"):
+        parent = parent / part
+        if parent.is_symlink() or (parent.exists() and not parent.is_dir()):
+            raise EvidenceError(f"unsafe E2E evidence parent: {parent}")
+        parent.mkdir(mode=0o700, exist_ok=True)
+    destination = parent / role
+    if destination.is_symlink() or (destination.exists() and not destination.is_dir()):
+        raise EvidenceError(f"unsafe E2E evidence destination: {destination}")
+    if destination.is_dir():
+        shutil.rmtree(destination)
+    destination.mkdir(parents=True, mode=0o700)
+    resolved = destination.resolve(strict=True)
+    try:
+        resolved.relative_to(workspace)
+    except ValueError as exc:
+        raise EvidenceError(f"E2E evidence destination escaped workspace: {resolved}") from exc
+    return resolved
+
+
+def validate_and_archive_e2e(
+    e2e: dict[str, Any],
+    *,
+    workspace_root: Path,
+    evidence_dir: Path,
+    archive_dir: Path,
+) -> EvidenceValidation:
+    errors = _validate_execution(e2e)
+    status = e2e.get("status")
+    if status == "unavailable":
+        return EvidenceValidation(tuple(errors), ())
+
+    artifact_values = e2e.get("artifacts")
+    if not isinstance(artifact_values, list) or not artifact_values:
+        errors.append("at least one E2E artifact is required")
+        return EvidenceValidation(tuple(errors), ())
+    if len(artifact_values) > MAX_EVIDENCE_FILES:
+        errors.append(f"too many E2E artifacts (maximum {MAX_EVIDENCE_FILES})")
+        return EvidenceValidation(tuple(errors), ())
+
+    evidence_root = evidence_dir.resolve()
+    workspace = workspace_root.resolve()
+    candidates: list[tuple[Path, Path]] = []
+    total_bytes = 0
+    for value in artifact_values:
+        if not isinstance(value, str) or not value.strip():
+            errors.append("E2E artifact paths must be non-empty strings")
+            continue
+        supplied = Path(value)
+        candidate = supplied if supplied.is_absolute() else workspace / supplied
+        if candidate.is_symlink():
+            errors.append(f"E2E artifact must not be a symlink: {value}")
+            continue
+        try:
+            resolved = candidate.resolve(strict=True)
+        except (OSError, RuntimeError):
+            errors.append(f"E2E artifact does not exist: {value}")
+            continue
+        try:
+            relative = resolved.relative_to(evidence_root)
+        except ValueError:
+            errors.append(f"E2E artifact is outside the assigned evidence directory: {value}")
+            continue
+        if not resolved.is_file():
+            errors.append(f"E2E artifact is not a file: {value}")
+            continue
+        stat = resolved.stat()
+        if stat.st_nlink != 1:
+            errors.append(f"E2E artifact must not be hard-linked: {value}")
+            continue
+        size = stat.st_size
+        if size <= 0:
+            errors.append(f"E2E artifact is empty: {value}")
+            continue
+        total_bytes += size
+        if total_bytes > MAX_EVIDENCE_BYTES:
+            errors.append(f"E2E artifacts exceed {MAX_EVIDENCE_BYTES // (1024 * 1024)} MiB total")
+            break
+        candidates.append((resolved, relative))
+
+    if errors:
+        return EvidenceValidation(tuple(errors), ())
+
+    archived: list[str] = []
+    try:
+        if archive_dir.exists():
+            shutil.rmtree(archive_dir)
+        for source, relative in candidates:
+            destination = archive_dir / relative
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source, destination)
+            archived.append(str(destination))
+    except OSError as exc:
+        shutil.rmtree(archive_dir, ignore_errors=True)
+        return EvidenceValidation((f"failed to archive E2E evidence: {exc}",), ())
+    return EvidenceValidation((), tuple(archived))
+
+
+def _validate_execution(e2e: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if e2e.get("required") is not True:
+        errors.append("tester did not mark the required E2E as required")
+    status = e2e.get("status")
+    if status == "unavailable":
+        return errors
+    if status not in {"passed", "failed"}:
+        errors.append(f"required E2E has invalid status: {status}")
+
+    command = e2e.get("command")
+    if (
+        not isinstance(command, list)
+        or not command
+        or not all(isinstance(item, str) and item.strip() for item in command)
+    ):
+        errors.append("E2E command must be a non-empty argv list")
+
+    exit_code = e2e.get("exit_code")
+    if isinstance(exit_code, bool) or not isinstance(exit_code, int):
+        errors.append("E2E exit_code must be an integer")
+    elif status == "passed" and exit_code != 0:
+        errors.append("passed E2E must have exit_code 0")
+    elif status == "failed" and exit_code == 0:
+        errors.append("failed E2E must have a nonzero exit_code")
+
+    evidence = e2e.get("evidence")
+    if (
+        not isinstance(evidence, list)
+        or not evidence
+        or not all(isinstance(item, str) and item.strip() for item in evidence)
+    ):
+        errors.append("E2E evidence summary must contain at least one non-empty item")
+    return errors