#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# File: src/scitex_writer/update.py

"""Public API for updating a scitex-writer project's engine files."""

from __future__ import annotations

from typing import Optional

from ._mcp.handlers._update import update_project as _update_project


def project(
    project_dir: str = ".",
    branch: Optional[str] = None,
    tag: Optional[str] = None,
    dry_run: bool = False,
    force: bool = False,
) -> dict:
    """Update engine files in an existing scitex-writer project.

    Syncs source code, build scripts, and templates from the installed
    scitex-writer package (or GitHub if branch/tag is specified).
    User content is never modified.

    Files synced:
        - src/scitex_writer/          (Python source code)
        - scripts/                    (shell compilation scripts)
        - compile.sh                  (main compile entry point)
        - 00_shared/latex_styles/     (LaTeX style files)
        - 01_manuscript/base.tex, 02_supplementary/base.tex, etc.
        - Makefile

    User content preserved (never touched):
        - 00_shared/ (authors, title, keywords, bibliography, claims)
        - 01_manuscript/contents/
        - 02_supplementary/contents/
        - 03_revision/contents/
        - GITIGNORED/, config/

    Parameters
    ----------
    project_dir : str
        Path to the scitex-writer project to update (default: current directory).
    branch : str, optional
        Pull from a specific template branch. Triggers GitHub clone.
    tag : str, optional
        Pull from a specific template tag/version. Triggers GitHub clone.
    dry_run : bool
        If True, report what would change without modifying any files.
    force : bool
        If True, skip the uncommitted-changes git safety check.

    Returns
    -------
    dict
        - success (bool)
        - version (str): package version
        - modified (list[str]): files that differ
        - added (list[str]): new files
        - unchanged (list[str]): identical files
        - backup_dir (str or None): path to backup
        - updated_paths (list[str]): legacy compat (modified + added)
        - dry_run (bool)
        - message (str)
        - error (str, only on failure)

    Examples
    --------
    >>> import scitex_writer as sw
    >>> sw.update.project("~/proj/my-paper", dry_run=True)
    >>> sw.update.project("~/proj/my-paper")
    >>> sw.update.project("~/proj/my-paper", tag="v2.7.1")
    """
    return _update_project(
        project_dir, branch=branch, tag=tag, dry_run=dry_run, force=force
    )


__all__ = ["project"]

# EOF
