"""Helpers to translate manifests into prompt-ready strings."""

from __future__ import annotations

from typing import List

from ..errors import PromptBuildError
from ..models import ActionGuideline, Manifest


def build_prompt_instructions(
    manifest: Manifest,
    *,
    include_api: bool = True,
) -> str:
    """Compose textual instructions suitable for feeding to an LLM."""

    try:
        lines: List[str] = []
        meta = manifest.metadata
        lines.append(
            f"Respect the site's agent permissions (schema {meta.schema_version}, last updated {meta.last_updated.isoformat()})."
        )

        if manifest.action_guidelines:
            lines.append("Action guidelines:")
            for guideline in manifest.action_guidelines:
                line = f"- {guideline.directive.value}: {guideline.description}"
                if guideline.exceptions:
                    line += f" (Exceptions: {guideline.exceptions})"
                lines.append(line)

        if include_api and manifest.api:
            lines.append("Preferred API integrations:")
            for api in manifest.api:
                segment = f"- {api.type} endpoint {api.endpoint} — {api.description}"
                if api.docs:
                    segment += f" (Docs: {api.docs})"
                lines.append(segment)

        if not lines:
            lines.append("No additional instructions provided by the site.")

        return "\n".join(lines)
    except Exception as exc:  # pragma: no cover - defensive
        raise PromptBuildError(f"Failed to render prompt instructions: {exc}") from exc