CLI¶

def debug_enabled() -> bool:
    """Return whether full tracebacks should be displayed."""
    try:
        return get_cli_state(create=False).show_tracebacks
    except RuntimeError:
        return False

def emit_error(message: str, *, exception: BaseException | None = None) -> None:
    """Log an error-level message to stderr respecting verbosity settings."""
    if exception is not None and getattr(exception, "_texsmith_logged", False):
        return
    render_message("error", message, exception=exception)

def emit_warning(message: str, *, exception: BaseException | None = None) -> None:
    """Log a warning-level message to stderr respecting verbosity settings."""
    render_message("warning", message, exception=exception)

def ensure_rich_compat() -> None:
    """Patch Rich stub modules provided by tests to expose required attributes."""
    import importlib.machinery
    import sys as _sys
    import types

    rich_mod = _sys.modules.get("rich")
    if rich_mod is None:
        return
    if getattr(rich_mod, "__spec__", None) is None:
        rich_mod.__spec__ = importlib.machinery.ModuleSpec("rich", loader=None)

    is_stub = getattr(rich_mod, "__file__", None) is None

    if is_stub:
        try:
            import typer.core as typer_core

            cast(Any, typer_core).HAS_RICH = False
        except ImportError:  # pragma: no cover - typer not available
            pass
        try:
            import typer.main as typer_main

            cast(Any, typer_main).HAS_RICH = False
        except ImportError:  # pragma: no cover - typer not available
            pass

    if not hasattr(rich_mod, "box"):
        box_module = types.ModuleType("rich.box")
        cast(Any, box_module).SQUARE = object()
        cast(Any, box_module).MINIMAL_DOUBLE_HEAD = object()
        cast(Any, box_module).SIMPLE = object()
        cast(Any, rich_mod).box = box_module
        _sys.modules.setdefault("rich.box", box_module)

def get_cli_state(
    ctx: typer.Context | click.Context | None = None,
    *,
    create: bool = True,
) -> CLIState:
    """Return the CLI state associated with the active Typer context."""
    if ctx is None:
        try:
            candidate = click.get_current_context(silent=True)
        except RuntimeError:
            candidate = None
        if isinstance(candidate, typer.Context):
            ctx = candidate

    state: CLIState | None = None

    if isinstance(ctx, typer.Context):
        current_ctx: typer.Context | None = ctx
        while current_ctx is not None:
            obj = getattr(current_ctx, "obj", None)
            if isinstance(obj, CLIState):
                state = obj
                break
            current_ctx = getattr(current_ctx, "parent", None)
        if state is None and create:
            state = CLIState()
            current_ctx = ctx
            current_ctx.obj = state
        if state is not None:
            _STATE_VAR.set(state)

    if state is None:
        fallback = _STATE_VAR.get(None)
        if fallback is None:
            if not create:
                raise RuntimeError("CLI state is not initialised for this context.")
            fallback = CLIState()
            _STATE_VAR.set(fallback)
        state = fallback

    return state

def main() -> None:
    """Entry point compatible with console scripts."""
    try:
        app()
    except typer.Exit:
        raise
    except KeyboardInterrupt as exc:
        if debug_enabled():
            raise
        emit_error("Operation cancelled by user.", exception=exc)
        raise typer.Exit(code=1) from exc
    except SystemExit:
        raise
    except Exception as exc:  # pragma: no cover - defensive catch-all
        from .state import get_cli_state

        state = get_cli_state()
        if state.show_tracebacks:
            from rich.traceback import Traceback

            tb = Traceback.from_exception(
                type(exc),
                exc,
                exc.__traceback__,
                show_locals=state.verbosity >= 2,
            )
            state.err_console.print(tb)
        else:
            emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc

def render(
    show_version: Annotated[
        bool,
        typer.Option(
            "--version",
            help="Show the TeXSmith version and exit.",
            is_eager=True,
        ),
    ] = False,
    list_templates_flag: Annotated[
        bool,
        typer.Option(
            "--list-templates",
            help="List available templates (builtin, entry-point, and local) and exit.",
            rich_help_panel=DIAGNOSTICS_PANEL,
        ),
    ] = False,
    list_bibliography: Annotated[
        bool,
        typer.Option(
            "--list-bibliography",
            help="Print bibliography details from provided .bib files and exit.",
            rich_help_panel=DIAGNOSTICS_PANEL,
        ),
    ] = False,
    verbose: Annotated[
        int,
        typer.Option(
            "--verbose",
            "-v",
            count=True,
            help=("Increase CLI verbosity. Combine multiple times for additional diagnostics."),
            rich_help_panel=DIAGNOSTICS_PANEL,
        ),
    ] = 0,
    debug: Annotated[
        bool,
        typer.Option(
            "--debug",
            help="Show full tracebacks when an unexpected error occurs.",
            rich_help_panel=DIAGNOSTICS_PANEL,
        ),
    ] = False,
    quiet: QuietOption = False,
    strict: StrictOption = False,
    deprecated: DeprecatedOption = None,
    diagnostics_json: DiagnosticsJsonOption = None,
    inputs: InputPathArgument = None,
    input_path: Annotated[
        Path | None,
        typer.Option(
            "--input-path",
            help="Internal helper used for programmatic invocation.",
            hidden=True,
        ),
    ] = None,
    output: OutputPathOption = None,
    base_level: BaseLevelOption = str(_REQUEST_DEFAULTS.base_level),
    strip_heading: StripHeadingOption = _REQUEST_DEFAULTS.strip_heading_all,
    no_promote_title: NoPromoteTitleOption = not _REQUEST_DEFAULTS.promote_title,
    no_title: NoTitleOption = _REQUEST_DEFAULTS.suppress_title,
    include_paths: IncludePathOption = None,
    no_copy_assets: NoCopyAssetsOption = not _REQUEST_DEFAULTS.copy_assets,
    convert_assets: ConvertAssetsOption = _REQUEST_DEFAULTS.convert_assets,
    hash_assets: HashAssetsOption = _REQUEST_DEFAULTS.hash_assets,
    http_user_agent: HttpUserAgentOption = _REQUEST_DEFAULTS.http_user_agent,
    diagrams_backend: Annotated[
        str | None,
        typer.Option(
            "--diagrams-backend",
            metavar="BACKEND",
            help="Force the backend for diagram conversion (draw.io, mermaid): playwright, local, or docker (auto-default).",
            case_sensitive=False,
        ),
    ] = _REQUEST_DEFAULTS.diagrams_backend,
    manifest: ManifestOptionWithShort = _REQUEST_DEFAULTS.manifest,
    make_deps: MakefileDepsOption = False,
    template: TemplateOption = None,
    embed_documents: Annotated[
        bool,
        typer.Option(
            "--embed",
            help="Embed converted documents into the main document instead linking them with \\input.",
        ),
    ] = _REQUEST_DEFAULTS.embed_documents,
    enable_fragments: EnableFragmentOption = None,
    disable_fragments: DisableFragmentOption = None,
    template_attributes: TemplateAttributeOption = None,
    debug_ir: DebugIrOption = None,
    classic_output: Annotated[
        bool,
        typer.Option(
            "--classic-output",
            help=("Display raw latexmk output without parsing."),
        ),
    ] = False,
    output_format: FormatOption = "latex",
    build_pdf: Annotated[
        bool,
        typer.Option(
            "-b",
            "--build",
            help="Invoke latexmk after rendering to compile the resulting LaTeX project.",
        ),
    ] = False,
    engine: Annotated[
        str,
        typer.Option(
            "-e",
            "--engine",
            help="LaTeX engine backend to use when building (tectonic, lualatex, xelatex).",
            rich_help_panel=OUTPUT_PANEL,
        ),
    ] = "tectonic",
    system_tectonic: Annotated[
        bool,
        typer.Option(
            "-S",
            "--system",
            help="Use the system Tectonic binary instead of the bundled download.",
            rich_help_panel=OUTPUT_PANEL,
        ),
    ] = False,
    language: LanguageOption = _REQUEST_DEFAULTS.language,
    numbering: NumberingOption = "backend",
    legacy_latex_accents: Annotated[
        bool,
        typer.Option(
            "--legacy-latex-accents",
            help=(
                "Escape accented characters and ligatures with legacy LaTeX macros instead of "
                "emitting Unicode glyphs (defaults to Unicode output)."
            ),
        ),
    ] = _REQUEST_DEFAULTS.legacy_latex_accents,
    slots: SlotsOption = None,
    open_log: OpenLogOption = False,
    snippet_dump_dir: Annotated[
        Path | None,
        typer.Option(
            "--dump-snippets",
            metavar="DIR",
            help="Copy snippet render sources (tex, aux files) into DIR for inspection.",
            rich_help_panel=DIAGNOSTICS_PANEL,
        ),
    ] = None,
    isolate_cache: Annotated[
        bool,
        typer.Option(
            "--isolate",
            help=(
                "Use a per-render TeX cache inside the output directory instead of the shared "
                "~/.cache/texsmith cache."
            ),
            rich_help_panel=OUTPUT_PANEL,
        ),
    ] = False,
    template_info_flag: TemplateInfoOption = False,
    template_scaffold: Annotated[
        Path | None,
        typer.Option(
            "--template-scaffold",
            metavar="DEST",
            help="Copy the selected template into DEST and exit.",
        ),
    ] = None,
    fonts_info: FontsInfoOption = False,
    print_context: Annotated[
        bool,
        typer.Option(
            "--print-context",
            help="Print resolved template context emitters/consumers and exit.",
            rich_help_panel=DIAGNOSTICS_PANEL,
        ),
    ] = False,
) -> None:
    """Convert Markdown documents into LaTeX or Typst sources and optionally build PDFs."""

    ctx = click.get_current_context(silent=True)
    typer_ctx = ctx if isinstance(ctx, typer.Context) else None

    if typer_ctx is not None and typer_ctx.resilient_parsing:
        return

    if show_version:
        typer.echo(get_version())
        raise typer.Exit()

    state = set_cli_state(ctx=typer_ctx, verbosity=verbose, debug=debug, quiet=quiet)
    output_format = (output_format or "latex").strip().lower()
    if output_format not in {"latex", "typst"}:
        raise typer.BadParameter("--format must be 'latex' or 'typst'.")
    # The Typst backend emits a ``.typ`` via the shared IR. With a template it
    # wraps the body in the template's [typst.template] scaffolding; without one
    # it emits a standalone document. It does not use the LaTeX fragment/engine
    # machinery, so the template *info/scaffold* flags are unsupported here.
    if output_format == "typst" and (template_info_flag or template_scaffold is not None):
        raise typer.BadParameter(
            "--format typst does not support --template-info/--template-scaffold."
        )
    numbering = (numbering or "backend").strip().lower()
    if numbering not in NUMBERING_MODES:
        raise typer.BadParameter("--numbering must be 'backend' or 'tmark'.")
    if deprecated is not None:
        deprecated = deprecated.strip().lower()
        if deprecated not in DEPRECATED_LEVELS:
            raise typer.BadParameter("--deprecated must be 'warning', 'info' or 'off'.")
    if snippet_dump_dir is not None:
        os.environ["TEXSMITH_SNIPPET_DUMP_DIR"] = str(snippet_dump_dir)

    if list_templates_flag:
        list_templates()
        raise typer.Exit()

    document_paths = list(inputs or [])
    if input_path is not None:
        if document_paths:
            raise typer.BadParameter("Provide either positional inputs or --input-path, not both.")
        document_paths = [input_path]

    if not document_paths:
        stdin_document = _read_stdin_document()
        if stdin_document is not None:
            document_paths = [stdin_document]

    try:
        split_result = _SERVICE.split_inputs(document_paths)
    except ConversionError as exc:
        emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc

    document_paths = split_result.documents
    bibliography_files = split_result.bibliography_files
    shared_front_matter = split_result.front_matter
    shared_front_matter_paths = split_result.front_matter_paths

    template_requested = template_info_flag or template_scaffold

    if list_bibliography:
        collection = BibliographyCollection()
        if bibliography_files:
            collection.load_files(bibliography_files)
        print_bibliography_overview(collection)
        raise typer.Exit()

    if not document_paths:
        if template_requested:
            identifier = template or "article"
            if template_info_flag:
                show_template_info(identifier)
            if template_scaffold:
                scaffold_template(identifier, template_scaffold)
            raise typer.Exit()
        raise typer.BadParameter(
            "Provide a Markdown (.md) source document or pipe content via stdin."
        )

    copy_assets = not no_copy_assets
    primary_front_matter: Mapping[str, Any] | None = shared_front_matter
    first_document = document_paths[0] if document_paths else None
    if primary_front_matter is None and first_document is not None:
        front_matter = _load_front_matter(first_document)
        if front_matter:
            primary_front_matter = front_matter

    fm_payload: dict[str, Any] = {}
    if isinstance(primary_front_matter, Mapping):
        fm_payload = dict(primary_front_matter)
        try:
            normalise_press_metadata(fm_payload)
        except PressMetadataError as exc:
            raise typer.BadParameter(str(exc)) from exc

    # The template has to be known before the two flags that report on one and
    # exit; everything else the flags imply is settled by ``resolve_render_plan``.
    template_param_source = ctx.get_parameter_source("template") if ctx else None
    no_promote_param_source = ctx.get_parameter_source("no_promote_title") if ctx else None
    if template is None and template_param_source in {None, ParameterSource.DEFAULT}:
        template = declared_template(primary_front_matter)

    if template_requested:
        identifier = template or "article"
        if template_info_flag:
            show_template_info(identifier)
        if template_scaffold:
            scaffold_template(identifier, template_scaffold)
        raise typer.Exit()

    attribute_overrides = _parse_template_attributes(template_attributes)
    has_attributes = bool(attribute_overrides)
    if attribute_overrides:
        try:
            normalise_press_metadata(attribute_overrides)
        except PressMetadataError as exc:
            raise typer.BadParameter(str(exc)) from exc
    if engine:
        attribute_overrides.setdefault("_texsmith_latex_engine", engine)
    if numbering != "backend":
        # Read by both IR backends (``core.conversion.resolution.numbering_mode``).
        attribute_overrides[NUMBERING_OVERRIDE_KEY] = numbering

    try:
        plan = resolve_render_plan(
            front_matter=fm_payload,
            template=template,
            build_pdf=build_pdf,
            output=output,
            output_format=output_format,
            print_context=print_context,
            has_attributes=has_attributes,
            no_title=no_title,
            strip_heading=strip_heading,
            no_promote_title=no_promote_title,
            no_promote_defaulted=no_promote_param_source in {None, ParameterSource.DEFAULT},
            base_level=base_level,
            base_level_defaulted=(ctx.get_parameter_source("base_level") if ctx else None)
            in {None, ParameterSource.DEFAULT},
            classic_output=classic_output,
            open_log=open_log,
            make_deps=make_deps,
            strict=strict,
            deprecated=deprecated,
            template_options=attribute_overrides,
            ci_runner=os.environ.get("ACT") == "true",
        )
    except RenderOptionError as exc:
        raise typer.BadParameter(str(exc)) from exc

    template = plan.template
    template_selected = plan.template_selected
    build_pdf = plan.build_pdf
    classic_output = plan.classic_output
    promote_title = plan.promote_title
    numbered = plan.numbered
    strict = plan.strict
    deprecated = plan.deprecated
    resolved_base_level = plan.base_level
    for notice in plan.notices:
        typer.echo(notice)

    if attribute_overrides:
        state.record_event("template_attributes", {"values": attribute_overrides})

    try:
        _, slot_assignments = organise_slot_overrides(slots, document_paths)
    except (typer.BadParameter, ValueError) as exc:
        raise typer.BadParameter(str(exc)) from exc

    state_slot_rows: list[dict[str, object]] = []
    for doc_path, entries in slot_assignments.items():
        for entry in entries:
            state_slot_rows.append(
                {
                    "document": _format_path_for_event(doc_path),
                    "slot": entry.slot,
                    "selector": entry.selector,
                    "include_document": entry.include_document,
                }
            )
    if state_slot_rows:
        state.record_event("slot_assignments", {"entries": state_slot_rows})

    emitter = _RenderEmitter(state=state, debug_enabled=debug_enabled(), deprecated=deprecated)
    presented_diagnostics = 0

    def _flush_diagnostics() -> None:
        """Close a phase: event lines, the diagnostics summary, the JSON dump, ``--strict``.

        Called at every exit of the command and, when building, once more
        before the engine runs so the ``.tex`` is there to inspect when
        ``--strict`` stops the run.
        """
        nonlocal presented_diagnostics
        lines: list[str] = list(consume_event_diagnostics(state))
        for line in lines:
            typer.echo(line)
        if len(emitter.sink) > presented_diagnostics:
            presented_diagnostics = len(emitter.sink)
            present_diagnostics_summary(state, emitter.sink)
        if diagnostics_json is not None:
            try:
                write_diagnostics_json(diagnostics_json, emitter.sink)
            except OSError as exc:
                emit_error(f"Failed to write diagnostics to '{diagnostics_json}': {exc}", exc)
                raise typer.Exit(code=1) from exc
        if strict and emitter.sink.strict_failed():
            emit_error("Diagnostics were recorded and --strict is on.")
            raise typer.Exit(code=1)

    debug_snapshot = debug_ir if debug_ir is not None else debug_enabled()

    output_mode, output_target = determine_output_target(template_selected, document_paths, output)
    resolved_output_target = output_target.resolve() if output_target is not None else None

    temp_render_dir: Path | None = None
    cleanup_render_dir = False
    cleanup_render_dir_path: Path | None = None
    final_pdf_target: Path | None = None

    if template_selected:
        if output_mode == "template-pdf":
            temp_render_dir = Path(tempfile.mkdtemp(prefix="texsmith-")).resolve()
            typer.echo(f"Using temporary output directory: {temp_render_dir}")
            cleanup_render_dir = True
            cleanup_render_dir_path = temp_render_dir
            final_pdf_target = resolved_output_target
        elif build_pdf and output_mode == "template" and output is None:
            # Keyed on the absence of ``-o`` itself, not on Typer's parameter
            # source: that source is ``None`` whenever the command runs without
            # a click context, which used to route an explicit ``-o dir`` to a
            # temporary directory and drop the PDF in the current directory.
            temp_render_dir = Path(tempfile.mkdtemp(prefix="texsmith-")).resolve()
            typer.echo(f"Using temporary output directory: {temp_render_dir}")
            cleanup_render_dir = True
            cleanup_render_dir_path = temp_render_dir
            primary_name = document_paths[0].stem if document_paths else "texsmith"
            final_pdf_target = Path.cwd() / f"{primary_name}.pdf"

    render_dir_path: Path | None = None
    if template_selected:
        render_dir_path = temp_render_dir or resolved_output_target
    elif output_mode == "directory":
        render_dir_path = resolved_output_target

    if template_selected and render_dir_path is None:
        raise typer.BadParameter("Unable to resolve template output directory.")

    if not embed_documents and template_selected and len(document_paths) == 1:
        embed_documents = True

    request_render_dir = render_dir_path

    request = ConversionRequest(
        copy_assets=copy_assets,
        convert_assets=convert_assets,
        hash_assets=hash_assets,
        manifest=manifest,
        persist_debug_ir=bool(debug_snapshot),
        language=language,
        http_user_agent=http_user_agent,
        legacy_latex_accents=legacy_latex_accents,
        diagrams_backend=diagrams_backend.lower() if isinstance(diagrams_backend, str) else None,
        documents=document_paths,
        bibliography_files=bibliography_files,
        front_matter=shared_front_matter,
        front_matter_paths=shared_front_matter_paths,
        slot_assignments=slot_assignments,
        include_paths=list(include_paths or ()),
        base_level=resolved_base_level,
        strip_heading_all=strip_heading if build_pdf else False,
        strip_heading_first_document=False if build_pdf else strip_heading,
        promote_title=promote_title,
        suppress_title=no_title,
        numbered=numbered,
        template=template,
        render_dir=request_render_dir,
        template_options=attribute_overrides,
        embed_documents=embed_documents,
        enable_fragments=enable_fragments or [],
        disable_fragments=disable_fragments or [],
        emitter=emitter,
    )
    state.record_event(
        "conversion_settings",
        {
            "copy_assets": copy_assets,
            "convert_assets": convert_assets,
            "hash_assets": hash_assets,
            "manifest": manifest,
        },
    )

    try:
        prepared = _SERVICE.prepare_documents(request)
    except UnsupportedInputError as exc:
        emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc
    except ConversionError as exc:
        emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc

    if output_format == "typst":
        typst_output_dir: Path | None = None
        if output_mode in {"directory", "template"}:
            typst_output_dir = resolved_output_target
        elif output_mode == "file" and resolved_output_target is not None:
            typst_output_dir = resolved_output_target.parent

        try:
            payload = render_typst_documents(
                prepared.documents, request, output_dir=typst_output_dir, emitter=emitter
            )
        except (ConversionError, TemplateError) as exc:
            # ``raise_conversion_error`` already put the record in the sink
            # and marked the exception as logged, so the message reaches the
            # console only if this exit flushes like every other one.
            _flush_diagnostics()
            emit_error(str(exc), exception=exc)
            raise typer.Exit(code=1) from exc

        if output_mode == "stdout":
            typer.echo(payload)
            _flush_diagnostics()
            return

        if output_mode == "file":
            if resolved_output_target is None:
                raise typer.BadParameter("Output path is required when writing Typst to a file.")
            target = resolved_output_target
        elif output_mode in {"directory", "template"}:
            if resolved_output_target is None:
                raise typer.BadParameter("Output directory is required when writing Typst files.")
            # Several documents make one ``main.typ``, as they make one ``main.tex``.
            stem = (
                prepared.documents[0].source_path.stem if len(prepared.documents) == 1 else "main"
            )
            target = resolved_output_target / f"{stem}.typ"
        else:
            raise RuntimeError(f"Unsupported output mode '{output_mode}' for Typst output.")
        try:
            write_output_file(target, payload)
        except OSError as exc:
            emit_error(str(exc), exception=exc)
            raise typer.Exit(code=1) from exc
        typer.echo(f"Wrote {target}")
        if build_pdf:
            ok, message = build_typst_pdf(target)
            typer.echo(message)
            if not ok and debug_enabled():
                raise typer.Exit(code=1)
        _flush_diagnostics()
        return

    engine_env_key = "TEXSMITH_SELECTED_ENGINE"
    previous_engine_value = os.environ.get(engine_env_key)
    if engine:
        os.environ[engine_env_key] = engine
    else:
        os.environ.pop(engine_env_key, None)
    try:
        response = _SERVICE.execute(request, prepared=prepared)
    except (TemplateError, ConversionError) as exc:
        emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc
    finally:
        if previous_engine_value is None:
            os.environ.pop(engine_env_key, None)
        else:
            os.environ[engine_env_key] = previous_engine_value

    if not template_selected:
        bundle = response.bundle

        if output_mode == "stdout":
            typer.echo(bundle.combined_output())
            _flush_diagnostics()
            return

        if output_mode == "file":
            if resolved_output_target is None:
                raise typer.BadParameter("Output path is required when writing to a file.")
            try:
                write_output_file(resolved_output_target, bundle.combined_output())
            except OSError as exc:
                emit_error(str(exc), exception=exc)
                raise typer.Exit(code=1) from exc
            present_conversion_summary(
                state=state,
                output_mode=output_mode,
                bundle=bundle,
                output_path=resolved_output_target,
                render_result=None,
            )
            _flush_diagnostics()
            return

        if output_mode == "directory":
            present_conversion_summary(
                state=state,
                output_mode=output_mode,
                bundle=bundle,
                output_path=request.render_dir,
                render_result=None,
            )
            _flush_diagnostics()
            return

        raise RuntimeError(f"Unsupported output mode '{output_mode}'.")

    render_result = response.render_result

    render_dir = render_result.main_tex_path.parent.resolve()

    if not build_pdf:
        present_conversion_summary(
            state=state,
            output_mode="template",
            bundle=None,
            output_path=render_dir,
            render_result=render_result,
        )
        if print_context:
            present_context_attributes(state=state, render_result=render_result)
        if fonts_info:
            present_fonts_info(state, render_result)
        _flush_diagnostics()
        return

    # Engine orchestration (binary selection, command/env build, run) lives in
    # adapters.latex.build.build_pdf; the CLI keeps only presentation, the PDF copy,
    # and dependency-file emission. ``build_pdf`` takes the runner as a parameter,
    # which is the seam a test substitutes.
    # The bodies are written: ``--strict`` decides here, before the engine runs.
    _flush_diagnostics()

    engine_choice = resolve_engine(engine, render_result.template_engine)
    state.console.print(f"[bold cyan]Running {engine_choice.label}…[/]")

    try:
        engine_result: EngineResult = pdf_build.build_pdf(
            render_result,
            engine=engine,
            classic_output=classic_output,
            isolate_cache=isolate_cache,
            console=state.console,
            verbosity=state.verbosity,
            use_system_tectonic=system_tectonic,
            run_engine=run_engine_command,
        )
    except ConversionError as exc:
        emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc
    except OSError as exc:
        if debug_enabled():
            raise
        emit_error(f"Failed to execute {engine_choice.label}: {exc}", exception=exc)
        raise typer.Exit(code=1) from exc

    if engine_result.returncode != 0:
        messages = engine_result.messages or parse_latex_log(engine_result.log_path)
        present_latex_failure(
            state=state,
            log_path=engine_result.log_path,
            messages=messages,
            open_log=open_log,
        )
        emit_error(f"{engine_choice.label} exited with status {engine_result.returncode}")
        raise typer.Exit(code=engine_result.returncode)

    pdf_path = engine_result.pdf_path
    final_pdf_path = pdf_path
    dep_file_path: Path | None = None

    if final_pdf_target is not None:
        final_destination = final_pdf_target
        try:
            final_destination.parent.mkdir(parents=True, exist_ok=True)
        except OSError as exc:
            emit_error(
                f"Unable to create output directory '{final_destination.parent}': {exc}",
                exc,
            )
            raise typer.Exit(code=1) from exc
        try:
            shutil.copy2(pdf_path, final_destination)
        except OSError as exc:
            emit_error(f"Failed to write PDF to '{final_destination}': {exc}", exc)
            raise typer.Exit(code=1) from exc
        final_pdf_path = final_destination

        # The reference inventory is written next to the intermediate ``.tex``,
        # which is a temporary directory in this mode: without this it would be
        # deleted along with it, and its pages — harvested from the ``.aux`` —
        # would never reach anyone.
        _deliver_reference_inventory(render_result.main_tex_path, final_destination.parent)

    if make_deps:
        dependency_paths: set[Path] = set()
        dependency_paths.update(document_paths)
        dependency_paths.update(bibliography_files)
        dependency_paths.update(shared_front_matter_paths)
        dependency_paths.add(render_result.main_tex_path)
        dependency_paths.update(render_result.fragment_paths)
        if render_result.bibliography_path:
            dependency_paths.add(render_result.bibliography_path)
        latexmkrc_candidate = render_dir / ".latexmkrc"
        if latexmkrc_candidate.exists():
            dependency_paths.add(latexmkrc_candidate)
        dependency_paths.update(getattr(render_result, "asset_paths", []))
        dependency_paths.update(getattr(render_result, "asset_sources", []))
        for key in getattr(render_result, "asset_map", {}) or {}:
            candidate_path = Path(key)
            if candidate_path.exists():
                dependency_paths.add(candidate_path)
        try:
            dep_file_path = _write_makefile_deps(final_pdf_path, dependency_paths)
        except OSError as exc:
            emit_error(f"Failed to write dependency file: {exc}", exc)
            raise typer.Exit(code=1) from exc

    present_build_summary(state=state, render_result=render_result, pdf_path=final_pdf_path)
    if fonts_info:
        present_fonts_info(state, render_result)
    if dep_file_path is not None:
        state.console.print(f"[cyan]Dependencies written to[/] {dep_file_path}")
    _flush_diagnostics()

    if cleanup_render_dir and cleanup_render_dir_path is not None:
        shutil.rmtree(cleanup_render_dir_path, ignore_errors=True)

def main() -> None:
    """Entry point compatible with console scripts."""
    try:
        app()
    except typer.Exit:
        raise
    except KeyboardInterrupt as exc:
        if debug_enabled():
            raise
        emit_error("Operation cancelled by user.", exception=exc)
        raise typer.Exit(code=1) from exc
    except SystemExit:
        raise
    except Exception as exc:  # pragma: no cover - defensive catch-all
        from .state import get_cli_state

        state = get_cli_state()
        if state.show_tracebacks:
            from rich.traceback import Traceback

            tb = Traceback.from_exception(
                type(exc),
                exc,
                exc.__traceback__,
                show_locals=state.verbosity >= 2,
            )
            state.err_console.print(tb)
        else:
            emit_error(str(exc), exception=exc)
        raise typer.Exit(code=1) from exc

def debug_enabled() -> bool:
    """Return whether full tracebacks should be displayed."""
    try:
        return get_cli_state(create=False).show_tracebacks
    except RuntimeError:
        return False

def emit_error(message: str, *, exception: BaseException | None = None) -> None:
    """Log an error-level message to stderr respecting verbosity settings."""
    if exception is not None and getattr(exception, "_texsmith_logged", False):
        return
    render_message("error", message, exception=exception)

def emit_warning(message: str, *, exception: BaseException | None = None) -> None:
    """Log a warning-level message to stderr respecting verbosity settings."""
    render_message("warning", message, exception=exception)

def ensure_rich_compat() -> None:
    """Patch Rich stub modules provided by tests to expose required attributes."""
    import importlib.machinery
    import sys as _sys
    import types

    rich_mod = _sys.modules.get("rich")
    if rich_mod is None:
        return
    if getattr(rich_mod, "__spec__", None) is None:
        rich_mod.__spec__ = importlib.machinery.ModuleSpec("rich", loader=None)

    is_stub = getattr(rich_mod, "__file__", None) is None

    if is_stub:
        try:
            import typer.core as typer_core

            cast(Any, typer_core).HAS_RICH = False
        except ImportError:  # pragma: no cover - typer not available
            pass
        try:
            import typer.main as typer_main

            cast(Any, typer_main).HAS_RICH = False
        except ImportError:  # pragma: no cover - typer not available
            pass

    if not hasattr(rich_mod, "box"):
        box_module = types.ModuleType("rich.box")
        cast(Any, box_module).SQUARE = object()
        cast(Any, box_module).MINIMAL_DOUBLE_HEAD = object()
        cast(Any, box_module).SIMPLE = object()
        cast(Any, rich_mod).box = box_module
        _sys.modules.setdefault("rich.box", box_module)

def exception_details(
    exception: BaseException | None, message: str, *, verbosity: int
) -> list[str]:
    """The lines ``-v`` adds under a message caused by ``exception`` (none below ``-v``)."""
    if exception is None or verbosity < 1:
        return []
    lines: list[str] = []
    detail = str(exception).strip()
    if detail and detail not in message:
        lines.append(detail)
    lines.append(f"type: {type(exception).__name__}")
    notes = getattr(exception, "__notes__", None)
    if notes:
        lines.extend(str(note) for note in notes)
    if verbosity >= 2:
        chain = _exception_chain(exception)
        if chain:
            lines.append("caused by:")
            lines.extend(f"  {entry}" for entry in chain)
    if verbosity >= 3:
        lines.append(f"repr: {exception!r}")
    return lines

def get_cli_state(
    ctx: typer.Context | click.Context | None = None,
    *,
    create: bool = True,
) -> CLIState:
    """Return the CLI state associated with the active Typer context."""
    if ctx is None:
        try:
            candidate = click.get_current_context(silent=True)
        except RuntimeError:
            candidate = None
        if isinstance(candidate, typer.Context):
            ctx = candidate

    state: CLIState | None = None

    if isinstance(ctx, typer.Context):
        current_ctx: typer.Context | None = ctx
        while current_ctx is not None:
            obj = getattr(current_ctx, "obj", None)
            if isinstance(obj, CLIState):
                state = obj
                break
            current_ctx = getattr(current_ctx, "parent", None)
        if state is None and create:
            state = CLIState()
            current_ctx = ctx
            current_ctx.obj = state
        if state is not None:
            _STATE_VAR.set(state)

    if state is None:
        fallback = _STATE_VAR.get(None)
        if fallback is None:
            if not create:
                raise RuntimeError("CLI state is not initialised for this context.")
            fallback = CLIState()
            _STATE_VAR.set(fallback)
        state = fallback

    return state

def render_message(
    level: str,
    message: str,
    *,
    exception: BaseException | None = None,
) -> None:
    """Render a formatted message to the console, including optional diagnostics."""
    state = get_cli_state()

    if level == "info":
        # Use a neutral console log for info to align with pipeline logging.
        console = state.console
        if getattr(console, "log", None):
            console.log(message)
        return

    from rich.text import Text

    style = "red" if level == "error" else "yellow"
    label_style = f"bold {style}"
    if hasattr(Text, "assemble"):
        text = Text.assemble((f"{level}: ", label_style), (message, style))
    else:  # pragma: no cover - stub Text fallback
        text = Text()
        text.append(f"{level}: ")
        text.append(message)
    extra_lines = exception_details(exception, message, verbosity=state.verbosity)

    if extra_lines:
        if hasattr(text, "append"):
            text.append("\n")
            if hasattr(Text, "assemble"):
                text.append("\n".join(extra_lines), style=style)
            else:  # pragma: no cover - stub Text fallback
                text.append("\n".join(extra_lines))
        else:  # pragma: no cover - fallback if text is a plain string
            text = f"{text}\n" + "\n".join(extra_lines)

    console = state.err_console if level != "info" else state.console
    if type(console).__name__.startswith("_Stub"):  # pragma: no cover - stub Console fallback
        target = sys.stderr if level != "info" else sys.stdout
        print(text if isinstance(text, str) else str(text), file=target)
    else:
        console.print(text)