"""Built-in internal extension descriptors."""

from __future__ import annotations

from markitect_tool.extension.registry import ExtensionDescriptor, ExtensionRegistry
from markitect_tool.extension.processing import ProcessingCapability
from markitect_tool.query import default_query_engine_registry
from markitect_tool.source import (
    default_source_adapter_registry,
    source_adapter_registry_descriptor,
)


def builtin_extension_registry() -> ExtensionRegistry:
    """Return descriptors for built-in Markitect extensions."""

    registry = default_query_engine_registry().extension_registry()
    for descriptor in _processor_descriptors() + [
        _extension_catalog_descriptor(),
        _generated_docs_descriptor(),
        _local_sqlite_backend_descriptor(),
        _workflow_engine_descriptor(),
        _runtime_context_descriptor(),
        _runtime_form_state_descriptor(),
        _runtime_assessment_descriptor(),
        _local_label_policy_descriptor(),
        _document_function_descriptor(),
        _agent_memory_descriptor(),
        source_adapter_registry_descriptor(),
    ]:
        registry.register(descriptor)
    for descriptor in default_source_adapter_registry().extension_descriptors():
        registry.register(descriptor)
    return registry


def _extension_catalog_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="extension.catalog",
        kind="extension-registry",
        summary="Inspectable catalog of built-in extension descriptors and CLI affordances.",
        capabilities=[
            ProcessingCapability(id="extensions", kind="inspect"),
            ProcessingCapability(id="cli", kind="inspect"),
        ],
        safety={"reads_files": False, "writes_files": False, "network": False},
        input_contract="Built-in ExtensionRegistry",
        output_contract="ExtensionDescriptor catalog | CliCommandSpec list",
        diagnostics_namespace="extension",
        provenance_prefix="extension.catalog",
        cli={
            "commands": [
                "mkt extension list",
                "mkt extension inspect",
                "mkt extension commands",
            ]
        },
        docs=["docs/internal-extension-framework.md"],
    )


def _generated_docs_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="docs.generated-reference",
        kind="documentation",
        summary="Generated CLI and API reference documentation from live command and API surfaces.",
        capabilities=[
            ProcessingCapability(id="docs", kind="generate"),
            ProcessingCapability(id="cli", kind="inspect"),
            ProcessingCapability(id="api", kind="inspect"),
        ],
        safety={"reads_files": False, "writes_files": True, "network": False},
        input_contract="Click command tree | markitect_tool.__all__",
        output_contract="Markdown reference document",
        diagnostics_namespace="docs",
        provenance_prefix="docs.generated_reference",
        cli={"commands": ["mkt docs cli", "mkt docs api"]},
        docs=["docs/cli-reference.md", "docs/api-reference.md"],
    )


def _processor_descriptors() -> list[ExtensionDescriptor]:
    return [
        ExtensionDescriptor(
            id="processor.identity",
            kind="processor",
            summary="Return fenced block content unchanged.",
            capabilities=[
                ProcessingCapability(id="processor", kind="execute"),
                ProcessingCapability(id="deterministic", kind="execution"),
            ],
            input_contract="ProcessorRequest",
            output_contract="ProcessorResult",
            diagnostics_namespace="processor",
            provenance_prefix="processor.identity",
            cli={"commands": ["mkt process"]},
            docs=["docs/processors.md"],
        ),
        ExtensionDescriptor(
            id="processor.uppercase",
            kind="processor",
            summary="Uppercase fenced block content deterministically.",
            capabilities=[
                ProcessingCapability(id="processor", kind="execute"),
                ProcessingCapability(id="deterministic", kind="execution"),
            ],
            input_contract="ProcessorRequest",
            output_contract="ProcessorResult",
            diagnostics_namespace="processor",
            provenance_prefix="processor.uppercase",
            cli={"commands": ["mkt process"]},
            docs=["docs/processors.md"],
        ),
        ExtensionDescriptor(
            id="processor.include",
            kind="processor",
            summary="Resolve a content reference into fenced block output.",
            capabilities=[
                ProcessingCapability(id="processor", kind="execute"),
                ProcessingCapability(id="references", kind="read"),
                ProcessingCapability(id="filesystem", kind="read"),
            ],
            safety={"reads_files": True, "writes_files": False, "network": False},
            input_contract="ProcessorRequest",
            output_contract="ProcessorResult",
            diagnostics_namespace="processor",
            provenance_prefix="processor.include",
            cli={"commands": ["mkt process"]},
            docs=["docs/processors.md", "docs/content-references.md"],
        ),
    ]


def _local_sqlite_backend_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="backend.local-sqlite",
        kind="backend",
        summary="Local SQLite snapshot, metadata, JSON, and FTS5 index backend.",
        capabilities=[
            ProcessingCapability(id="snapshots", kind="backend"),
            ProcessingCapability(id="ast", kind="backend"),
            ProcessingCapability(id="json", kind="backend"),
            ProcessingCapability(id="fts", kind="backend"),
            ProcessingCapability(id="sql", kind="backend"),
            ProcessingCapability(id="provenance", kind="backend"),
            ProcessingCapability(id="policy_filter", kind="backend"),
        ],
        safety={"reads_files": True, "writes_local_cache": True, "network": False},
        input_contract="Markdown files/directories",
        output_contract="SQLite snapshot/index store",
        diagnostics_namespace="backend.local_sqlite",
        provenance_prefix="local_snapshot_store",
        cli={"commands": ["mkt cache init", "mkt cache index", "mkt cache query", "mkt search"]},
        docs=["docs/local-index-backend.md", "docs/backend-fabric.md"],
        examples=["examples/backends/local-sqlite-backend.md"],
    )


def _workflow_engine_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="workflow.markdown-dataflow",
        kind="workflow-engine",
        summary="Declarative Markdown dataflow workflow engine.",
        capabilities=[
            ProcessingCapability(id="workflow", kind="execute"),
            ProcessingCapability(id="markdown", kind="read"),
            ProcessingCapability(id="templates", kind="execute"),
            ProcessingCapability(id="provenance", kind="emit"),
        ],
        safety={
            "reads_files": True,
            "writes_output_files": True,
            "network": False,
            "assisted_generation": "adapter-only",
        },
        input_contract="Markdown/YAML workflow definition",
        output_contract="WorkflowRunResult",
        diagnostics_namespace="workflow",
        provenance_prefix="workflow",
        cli={"commands": ["mkt workflow inspect", "mkt workflow plan", "mkt workflow run"]},
        docs=["docs/workflow-definition-standard.md"],
        examples=["examples/workflows/adr-release-notes.workflow.md"],
    )


def _runtime_context_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="runtime.context",
        kind="runtime",
        summary="YAML/JSON runtime context loader for document contracts.",
        capabilities=[
            ProcessingCapability(id="context", kind="read"),
            ProcessingCapability(id="json-schema", kind="validate"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={"reads_files": True, "network": False},
        input_contract="YAML/JSON runtime context file",
        output_contract="RuntimeContext",
        diagnostics_namespace="runtime.context",
        provenance_prefix="runtime.context",
        cli={"commands": ["mkt contract check --context", "mkt contract form-state"]},
        docs=["docs/runtime-context-forms-assessments.md"],
        examples=["examples/runtime/business-letter.context.yaml"],
    )


def _runtime_form_state_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="runtime.form-state",
        kind="runtime",
        summary="UI-neutral field prefill, validation, and dynamic rule engine.",
        capabilities=[
            ProcessingCapability(id="forms", kind="evaluate"),
            ProcessingCapability(id="rules", kind="evaluate"),
            ProcessingCapability(id="contracts", kind="validate"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={"reads_files": False, "network": False},
        input_contract="Document + DocumentContract + RuntimeContext",
        output_contract="FormState",
        diagnostics_namespace="runtime",
        provenance_prefix="runtime.form_state",
        cli={"commands": ["mkt contract form-state"]},
        docs=["docs/runtime-context-forms-assessments.md"],
        examples=["examples/runtime/workplan-dynamic.contract.md"],
    )


def _runtime_assessment_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="runtime.assessment",
        kind="assessment-runner",
        summary="Provider-neutral rubric assessment request, result, and cache boundary.",
        capabilities=[
            ProcessingCapability(id="assessment", kind="execute"),
            ProcessingCapability(id="rubrics", kind="read"),
            ProcessingCapability(id="cache-key", kind="compute"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={"network": "adapter-only", "provider_calls": "adapter-only"},
        input_contract="AssessmentRequest",
        output_contract="AssessmentResult",
        diagnostics_namespace="runtime.assessment",
        provenance_prefix="runtime.assessment",
        docs=["docs/runtime-context-forms-assessments.md"],
        examples=["examples/runtime/concept-note-assessment.contract.md"],
        metadata={"provider_implementation": "external adapter required"},
    )


def _local_label_policy_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="policy.local-label",
        kind="policy-gateway",
        summary="Local label, trust-zone, and path policy gateway.",
        capabilities=[
            ProcessingCapability(id="policy", kind="authorize"),
            ProcessingCapability(id="policy_filter", kind="filter"),
            ProcessingCapability(id="identity_claims", kind="normalize"),
            ProcessingCapability(id="resource_manifest", kind="register"),
            ProcessingCapability(id="decision_log", kind="emit"),
            ProcessingCapability(id="diagnostics", kind="emit"),
            ProcessingCapability(id="provenance", kind="emit"),
        ],
        safety={"network": False, "external_policy_engine": False},
        input_contract="PolicySubject + PolicyObject + local label policy",
        output_contract="PolicyDecision | PolicyFilterResult",
        diagnostics_namespace="policy",
        provenance_prefix="policy.local_label",
        cli={
            "commands": [
                "mkt policy check",
                "mkt policy subject",
                "mkt policy resource-manifest",
                "mkt cache query --policy",
                "mkt search --policy",
            ]
        },
        docs=["docs/access-control-policy-gateway.md"],
        examples=["examples/policy/local-label-policy.yaml"],
        metadata={
            "external_adapters": [
                "IdentityClaimsAdapter",
                "DirectoryGroupResolver",
                "EnterprisePolicyMapper",
                "RelationshipPolicyAdapter",
                "RulePolicyAdapter",
                "DecisionLogStore",
            ]
        },
    )


def _document_function_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="document.function",
        kind="document-function",
        summary="Markdown-native deterministic document function registry and evaluator.",
        capabilities=[
            ProcessingCapability(id="document_function", kind="execute"),
            ProcessingCapability(id="deterministic", kind="execution"),
            ProcessingCapability(id="diagnostics", kind="emit"),
            ProcessingCapability(id="provenance", kind="emit"),
        ],
        safety={
            "network": False,
            "filesystem": False,
            "assisted_generation": False,
            "external_process": False,
        },
        input_contract="Markdown with {{mkt:function ...}} or mkt-function fences",
        output_contract="DocumentFunctionEvaluationResult",
        diagnostics_namespace="document_function",
        provenance_prefix="document_function",
        cli={"commands": ["mkt function list", "mkt function check", "mkt function render"]},
        docs=["docs/document-functions.md"],
        examples=["examples/functions/basic-functions.md"],
        metadata={
            "execution": "deterministic-only",
            "external_policy_services_required": False,
        },
    )


def _agent_memory_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="memory.context-package",
        kind="memory-registry",
        summary="Local agent working-memory context package registry and activation lifecycle.",
        capabilities=[
            ProcessingCapability(id="context_packages", kind="create"),
            ProcessingCapability(id="context_activation", kind="execute"),
            ProcessingCapability(id="snapshots", kind="read"),
            ProcessingCapability(id="fts", kind="read"),
            ProcessingCapability(id="policy_filter", kind="filter"),
            ProcessingCapability(id="provenance", kind="emit"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={
            "reads_files": True,
            "writes_local_context_registry": True,
            "network": False,
            "assisted_generation": False,
            "external_policy_engine": False,
        },
        input_contract="Selector/search/manifest + local snapshots/documents",
        output_contract="ContextPackage | ContextActivation",
        diagnostics_namespace="memory",
        provenance_prefix="memory.context_package",
        cli={
            "commands": [
                "mkt context pack",
                "mkt context activate",
                "mkt context deactivate",
                "mkt context explain",
                "mkt context refresh",
                "mkt context list",
            ]
        },
        docs=[
            "docs/agent-working-memory.md",
            "docs/agent-working-memory-thought-experiment.md",
        ],
        examples=["examples/memory/workplan-context.manifest.yaml"],
        metadata={
            "external_policy_services_required": False,
            "assisted_summaries": "future adapter-only",
            "default_registry": ".markitect/context",
        },
    )