graph-agents-cli 0.3.1__py3-none-any.whl

graph_agents_cli/scaffold/utils/merge.py

@@ -0,0 +1,970 @@
+# Copyright 2026 Google LLC
+# Modifications Copyright 2026 graph-agents-cli contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared merge utilities for upgrade and enhance commands.
+
+Functions for generating template snapshots, displaying comparison results,
+resolving conflicts, and applying file changes. ``run_three_way_merge`` is the
+orchestrator shared by *upgrade* and *enhance*.
+
+Baseline policy: the old snapshot is regenerated by the exact prior CLI
+version (``uvx --from <pinned_install_spec(version)> graph-agents-cli``), or by
+the exact build a caller names (``old_source``: ``scaffold upgrade
+--baseline-ref``, or the commit a manifest records for a build between
+releases), because the current templates would misclassify files that changed
+between the two. When that build cannot be fetched and run, or
+``GRAPH_AGENTS_CLI_INSTALL_SPEC`` is set without ``{version}`` (it would install
+some other build), the merge stops with no changes unless ``baseline="current"``
+was passed, an explicit and logged opt-in to compare against the current templates.
+"""
+
+import difflib
+import logging
+import pathlib
+import shutil
+import tempfile
+from collections.abc import Callable
+from typing import Literal
+
+import click
+from rich.markup import escape
+from rich.prompt import Prompt
+
+from graph_agents_cli._output import Console
+
+from .upgrade import (
+    MERGE_DEPENDENCY_HANDLERS,
+    WRITE_DEPENDENCY_HANDLERS,
+    DependencyReadError,
+    DependencyResolution,
+    FileCompareResult,
+    Followup,
+    compare_all_files,
+    group_results_by_action,
+    is_image_definition,
+    merged_config_text,
+)
+from .version import BaselineSource
+
+console = Console()
+
+# Maximum characters to display when showing diffs
+MAX_DIFF_DISPLAY_CHARS = 2000
+
+Baseline = Literal["authentic", "current"]
+BASELINE_CURRENT_LABEL = "(baseline: current templates, --baseline current)"
+
+
+def is_fetchable_version(version: str) -> bool:
+    """True if ``version`` is worth attempting to fetch (a released version).
+
+    Rejects the unknown-version sentinel and unparseable strings; whether the
+    release actually exists is confirmed only by the fetch in ``_run_pinned_create``.
+    """
+    from packaging import version as pkg_version
+
+    from .version import UNKNOWN_VERSION
+
+    if version == UNKNOWN_VERSION:
+        return False
+
+    try:
+        pkg_version.parse(version)
+    except Exception:
+        return False
+    return True
+
+
+def _run_vendored_create(
+    args: list[str],
+    output_dir: pathlib.Path,
+    project_name: str,
+) -> bool:
+    """Generate the snapshot in-process with the bundled create command."""
+    from click import Context
+
+    from ..commands.create import create
+
+    cli_args = [project_name]
+    cli_args.extend(["--output-dir", str(output_dir)])
+    # This runs in-process, so its output lands in the user's terminal.
+    # --quiet keeps it silent. The pinned path deliberately does not pass it:
+    # older published releases might reject it, and uvx output is captured.
+    cli_args.extend(["--auto-approve", "--skip-deps", "--skip-checks", "--quiet"])
+    cli_args.extend(args)
+
+    logging.debug("Running vendored create command with args: %s", cli_args)
+
+    try:
+        ctx = Context(create, info_name="create")
+        create.parse_args(ctx, list(cli_args))
+        ctx.invoke(create, **ctx.params)
+
+        expected_dir = output_dir / project_name
+        if not expected_dir.exists():
+            logging.error(
+                f"Create command succeeded but project directory not found: {expected_dir}"
+            )
+            return False
+
+        return True
+    except SystemExit as e:
+        if e.code == 0:
+            return True
+        logging.error(f"Create command failed with exit code {e.code}")
+        return False
+    except Exception as e:
+        logging.error(f"Error running create command: {e}")
+        return False
+
+
+def _run_pinned_create(
+    args: list[str],
+    output_dir: pathlib.Path,
+    project_name: str,
+    version: str,
+    source: BaselineSource | None = None,
+) -> bool:
+    """Generate the snapshot via ``uvx --from <spec> graph-agents-cli scaffold create``.
+
+    The spec is ``source.spec`` when a build was named (``--baseline-ref``, or
+    the commit a manifest records), else ``pinned_install_spec(version)``.
+    Returns true if the snapshot was generated, false otherwise.
+    """
+    from graph_agents_cli._runner import run_resolved
+
+    from .version import PACKAGE_NAME, pinned_install_spec
+
+    spec = source.spec if source is not None else pinned_install_spec(version)
+    if spec is None:
+        return False
+    refresh = ["--refresh-package", PACKAGE_NAME] if source is not None and source.refresh else []
+    cmd = [
+        "uvx",
+        *refresh,
+        "--from",
+        spec,
+        PACKAGE_NAME,
+        "scaffold",
+        "create",
+        project_name,
+        "--output-dir",
+        str(output_dir),
+        "--auto-approve",
+        "--skip-deps",
+        "--skip-checks",
+        *args,
+    ]
+
+    logging.debug("Running pinned create via uvx: %s", cmd)
+    label = source.label if source is not None else version
+
+    try:
+        result = run_resolved(cmd, capture_output=True, text=True)
+    except Exception as e:
+        logging.error("Could not run uvx to generate the %s template: %s", label, e)
+        return False
+
+    if result.returncode != 0:
+        logging.debug("uvx create for %s exited %s:\n%s", label, result.returncode, result.stderr)
+        tail = [line for line in (result.stderr or "").splitlines() if line.strip()][-5:]
+        logging.error(
+            "Failed to generate the %s template via uvx%s",
+            label,
+            (":\n  " + "\n  ".join(tail)) if tail else ".",
+        )
+        return False
+
+    expected_dir = output_dir / project_name
+    if not expected_dir.exists():
+        logging.error(
+            "uvx create for %s reported success but %s is missing.",
+            label,
+            expected_dir,
+        )
+        return False
+
+    return True
+
+
+def run_create_command(
+    args: list[str],
+    output_dir: pathlib.Path,
+    project_name: str,
+    version: str | None = None,
+    baseline: Baseline = "authentic",
+    source: BaselineSource | None = None,
+) -> bool:
+    """Generate a template snapshot for the 3-way upgrade/enhance merge.
+
+    A ``source`` (a named build: ``--baseline-ref``, or the commit a manifest
+    records) is rendered by that build through ``uvx``, whatever its version.
+    Otherwise no ``version``, or the running CLI's own version, renders with the
+    bundled templates, and a prior ``version`` is re-created by that exact
+    release through ``uvx`` (the authentic baseline). If the build cannot be
+    fetched and run (source unreachable, version absent, ``uvx`` missing,
+    unparseable version), the snapshot is NOT generated and False is returned,
+    so the caller stops with no changes. ``baseline="current"`` is the explicit,
+    logged opt-in to render the old snapshot with the current templates instead.
+
+    Returns True if the template was generated, False otherwise.
+    """
+    from .version import (
+        PACKAGE_NAME,
+        get_current_version,
+        pinned_install_spec,
+        pinned_spec_unavailable,
+    )
+
+    if source is not None and baseline == "authentic":
+        if _run_pinned_create(args, output_dir, project_name, version or "", source):
+            return True
+        logging.error(
+            "Could not build the %s baseline from %s via uvx (source unreachable, ref "
+            "absent, or uvx missing). Nothing was changed.",
+            PACKAGE_NAME,
+            source.label,
+        )
+        return False
+
+    if not version or version == get_current_version():
+        return _run_vendored_create(args, output_dir, project_name)
+
+    if baseline == "current":
+        logging.warning(
+            "Baseline override: rendering the %s snapshot with the CURRENT templates "
+            "(--baseline current). Files deleted or updated between %s and now may be "
+            "misclassified; review the result.",
+            version,
+            version,
+        )
+        console.print(
+            f"[yellow]Using the current templates as the {version} baseline "
+            "(--baseline current).[/yellow]"
+        )
+        return _run_vendored_create(args, output_dir, project_name)
+
+    if not is_fetchable_version(version):
+        logging.error(
+            "Cannot fetch %s@%s to build the authentic prior-version baseline: the "
+            "version is not a fetchable release. An inauthentic baseline would "
+            "misclassify files, so nothing was changed. Re-run with "
+            "`--baseline current` to compare against the current templates instead.",
+            PACKAGE_NAME,
+            version,
+        )
+        return False
+
+    if pinned_install_spec(version) is None:
+        logging.error(
+            "Cannot build the authentic %s@%s baseline: %s. Nothing was changed; or re-run "
+            "with `--baseline current` to compare against the current templates instead.",
+            PACKAGE_NAME,
+            version,
+            pinned_spec_unavailable(version),
+        )
+        return False
+
+    if _run_pinned_create(args, output_dir, project_name, version):
+        return True
+
+    logging.error(
+        "Could not build the %s@%s baseline via uvx (source unreachable, version "
+        "absent, or uvx missing). An inauthentic baseline would misclassify files, "
+        "so nothing was changed. Re-run with `--baseline current` to compare against "
+        "the current templates instead.",
+        PACKAGE_NAME,
+        version,
+    )
+    return False
+
+
+def display_results(
+    groups: dict[str, list[FileCompareResult]],
+    dep_resolutions: list[DependencyResolution],
+    dry_run: bool = False,
+    baseline_current_of: str | None = None,
+) -> None:
+    """Display the comparison results grouped by action.
+
+    ``baseline_current_of`` is the prior version when its snapshot was rendered
+    with the current templates (``--baseline current``): a file that differs
+    from them is then either the user's edit or one the templates changed
+    since that version, and the preserve list says so.
+    """
+    if groups["auto_update"]:
+        console.print("[bold green]Will auto-update (unchanged by you):[/bold green]")
+        for result in groups["auto_update"]:
+            console.print(f"  [green]✓[/green] {result.path}")
+        console.print()
+
+    preserved_user_modified = [
+        r for r in groups["preserve"] if r.preserve_type == "gacli_unchanged"
+    ]
+    if preserved_user_modified:
+        if baseline_current_of:
+            console.print(
+                "[bold cyan]Will preserve (differs from the current template):[/bold cyan]\n"
+                f"[yellow]  --baseline current cannot tell your edits from template changes "
+                f"since {baseline_current_of}: each file below that you did not edit keeps "
+                f"its {baseline_current_of} content, and dependency changes since then are "
+                "not merged. Prefer the authentic baseline.[/yellow]"
+            )
+        else:
+            console.print(
+                "[bold cyan]Will preserve (you modified, template unchanged):[/bold cyan]"
+            )
+        for result in preserved_user_modified:
+            console.print(f"  [cyan]✓[/cyan] {result.path}")
+        console.print()
+
+    skipped = [r for r in groups["skip"] if r.category in ("agent_code", "config_files")]
+    if skipped:
+        console.print("[dim]Skipping (your code and config):[/dim]")
+        for result in skipped:
+            console.print(f"  [dim]-[/dim] {result.path}")
+        console.print()
+
+    if groups.get("merge"):
+        console.print(
+            "[bold green]Will merge the template's change into your edited config:[/bold green]"
+        )
+        for result in groups["merge"]:
+            partly = " [dim](except keys you changed too)[/dim]" if result.followup else ""
+            console.print(f"  [green]✓[/green] {result.path}{partly}")
+        console.print()
+
+    if groups["new"]:
+        console.print("[bold yellow]Files to add:[/bold yellow]")
+        for result in groups["new"]:
+            console.print(f"  [yellow]+[/yellow] {result.path}")
+        console.print()
+
+    if groups["removed"]:
+        console.print("[bold yellow]Files to remove:[/bold yellow]")
+        for result in groups["removed"]:
+            console.print(f"  [yellow]-[/yellow] {result.path}")
+        console.print()
+
+    if groups["conflict"]:
+        console.print("[bold red]Conflicts (both changed):[/bold red]")
+        for result in groups["conflict"]:
+            console.print(f"  [red]⚠[/red]  {result.path}")
+        if not dry_run:
+            console.print("[dim]  You'll be prompted to resolve each conflict.[/dim]")
+        console.print()
+
+    # Only show deps that actually changed, not unchanged ones.
+    changed = [r for r in dep_resolutions if r.status != "unchanged"]
+    if changed:
+        console.print("[bold]Dependency changes:[/bold]")
+        for resolution in changed:
+            dep_name = escape(resolution.name)
+            old_ver = escape(resolution.old_version or "")
+            new_ver = escape(resolution.new_version or "")
+            if resolution.status == "updated":
+                console.print(f"  [green]✓[/green] Update: {dep_name} {old_ver} → {new_ver}")
+            elif resolution.status == "added":
+                console.print(f"  [green]+[/green] Add: {dep_name}{new_ver}")
+            elif resolution.status == "kept":
+                console.print(f"  [cyan]✓[/cyan] Keep (yours): {dep_name}{old_ver}")
+            elif resolution.status == "removed":
+                console.print(f"  [yellow]-[/yellow] Remove: {dep_name}{old_ver}")
+        console.print()
+
+
+def handle_conflict(
+    *,
+    result: FileCompareResult,
+    project_dir: pathlib.Path,
+    new_template_dir: pathlib.Path,
+    auto_approve: bool,
+    prefer_new: bool = False,
+    interactive: bool = False,
+) -> str:
+    """Handle a file conflict.
+
+    Returns:
+        Action taken: "kept", "kept_all", "updated", "updated_all", or "skipped"
+    """
+    if not interactive:
+        # Non-interactive (auto-approve or strict programmatic): keep the user's version
+        if prefer_new:
+            console.print(f"  [green]Using new version: {result.path}[/green]")
+            return "updated"
+        logging.warning(
+            "Conflict: %s: keeping your version (use --prefer-new to override)",
+            result.path,
+        )
+        return "kept"
+
+    console.print(f"\n[bold yellow]Conflict: {result.path}[/bold yellow]")
+    console.print(f"  Reason: {result.reason}")
+
+    choice = Prompt.ask(
+        "  (v)iew diff, (k)eep yours, (K)eep all, (u)se new, (U)se all, (s)kip",
+        choices=["v", "k", "K", "u", "U", "s"],
+        default="k",
+    )
+
+    if choice == "v":
+        current_file = project_dir / result.path
+        new_file = new_template_dir / result.path
+
+        try:
+            current_lines = current_file.read_text(encoding="utf-8").splitlines(keepends=True)
+            new_lines = new_file.read_text(encoding="utf-8").splitlines(keepends=True)
+
+            diff_lines = list(
+                difflib.unified_diff(
+                    current_lines,
+                    new_lines,
+                    fromfile=f"Your version: {result.path}",
+                    tofile=f"New version: {result.path}",
+                )
+            )
+            diff_output = "".join(diff_lines)
+
+            console.print()
+            if diff_output:
+                if len(diff_output) > MAX_DIFF_DISPLAY_CHARS:
+                    console.print(diff_output[:MAX_DIFF_DISPLAY_CHARS])
+                    console.print("[dim]... (truncated)[/dim]")
+                else:
+                    console.print(diff_output)
+            else:
+                console.print("[dim]No differences found[/dim]")
+        except Exception as e:
+            console.print(f"[red]Could not show diff: {e}[/red]")
+
+        choice = Prompt.ask(
+            "  (k)eep yours, (K)eep all, (u)se new, (U)se all, (s)kip",
+            choices=["k", "K", "u", "U", "s"],
+            default="k",
+        )
+
+    if choice == "K":
+        console.print("  [cyan]Keeping your version for all conflicts[/cyan]")
+        return "kept_all"
+    elif choice == "U":
+        console.print("  [green]Using new version for all conflicts[/green]")
+        return "updated_all"
+    elif choice == "k":
+        console.print("  [cyan]Keeping your version[/cyan]")
+        return "kept"
+    elif choice == "u":
+        return "updated"
+    else:
+        return "skipped"
+
+
+def copy_file(src: pathlib.Path, dst: pathlib.Path) -> bool:
+    """Copy a file, creating parent directories as needed."""
+    if not src.exists():
+        return False
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dst)
+    return True
+
+
+def apply_changes(
+    *,
+    groups: dict[str, list[FileCompareResult]],
+    project_dir: pathlib.Path,
+    new_template_dir: pathlib.Path,
+    auto_approve: bool,
+    dry_run: bool,
+    prefer_new: bool = False,
+    interactive: bool = False,
+    old_template_dir: pathlib.Path | None = None,
+) -> dict[str, int]:
+    """Apply file changes to the project (``merge`` results need ``old_template_dir``)."""
+    counts = {
+        "updated": 0,
+        "added": 0,
+        "removed": 0,
+        "skipped": 0,
+        "conflicts_kept": 0,
+        "conflicts_updated": 0,
+        "merged": 0,
+    }
+
+    if dry_run:
+        console.print("[bold yellow]Dry run - no changes made[/bold yellow]")
+        return counts
+
+    for result in groups["auto_update"]:
+        if copy_file(new_template_dir / result.path, project_dir / result.path):
+            counts["updated"] += 1
+
+    for result in groups.get("merge", []):
+        merged = (
+            merged_config_text(project_dir, old_template_dir, new_template_dir, result.path)
+            if old_template_dir is not None
+            else None
+        )
+        if merged is None:
+            # Classified as mergeable a moment ago; never guess if that changed.
+            counts["skipped"] += 1
+            continue
+        (project_dir / result.path).write_text(merged, encoding="utf-8")
+        counts["merged"] += 1
+
+    for result in groups["new"]:
+        if copy_file(new_template_dir / result.path, project_dir / result.path):
+            counts["added"] += 1
+
+    for result in groups["removed"]:
+        file_path = project_dir / result.path
+        if file_path.exists():
+            file_path.unlink()
+            counts["removed"] += 1
+
+    if groups["conflict"]:
+        console.print()
+        console.print("[bold]Resolving conflicts:[/bold]")
+
+    bulk_action = None  # "keep" or "update" when user chooses K or U
+    for result in groups["conflict"]:
+        if bulk_action == "keep":
+            console.print(f"  [dim]Keeping your version: {result.path}[/dim]")
+            counts["conflicts_kept"] += 1
+            continue
+        elif bulk_action == "update":
+            if copy_file(new_template_dir / result.path, project_dir / result.path):
+                console.print(f"  [green]Updated: {result.path}[/green]")
+                counts["conflicts_updated"] += 1
+            continue
+
+        action = handle_conflict(
+            result=result,
+            project_dir=project_dir,
+            new_template_dir=new_template_dir,
+            auto_approve=auto_approve,
+            prefer_new=prefer_new,
+            interactive=interactive,
+        )
+        if action == "kept_all":
+            counts["conflicts_kept"] += 1
+            bulk_action = "keep"
+        elif action == "updated_all":
+            if copy_file(new_template_dir / result.path, project_dir / result.path):
+                counts["conflicts_updated"] += 1
+            bulk_action = "update"
+        elif action == "updated":
+            if copy_file(new_template_dir / result.path, project_dir / result.path):
+                counts["conflicts_updated"] += 1
+        elif action == "kept":
+            counts["conflicts_kept"] += 1
+        else:
+            counts["skipped"] += 1
+
+    return counts
+
+
+class IncompleteMergeError(click.ClickException):
+    """The merge was applied, but items marked required are left for the developer (exit 1).
+
+    Until they are done the project does not build or deploy with the settings
+    its manifest records, so a script must not carry on as if it did.
+    """
+
+    exit_code = 1
+
+
+def print_followups(followups: list[str | Followup], *, dry_run: bool = False) -> None:
+    """Print what the developer still has to do by hand, one numbered item each."""
+    if not followups:
+        return
+    console.print()
+    title = "Left for you after applying" if dry_run else "Left for you"
+    console.print(f"[bold yellow]{title}:[/bold yellow]")
+    for number, item in enumerate(followups, 1):
+        text = item.text if isinstance(item, Followup) else item
+        required = isinstance(item, Followup) and item.required
+        first, _, rest = text.partition("\n")
+        mark = "[bold red](required)[/bold red] " if required else ""
+        console.print(f"  {number}. {mark}{escape(first)}")
+        if rest:
+            console.print(rest.rstrip("\n"), highlight=False, markup=False)
+
+
+def _finish(followups: list[str | Followup], *, dry_run: bool) -> None:
+    """Print the follow-ups; raise :class:`IncompleteMergeError` when a required one is left."""
+    print_followups(followups, dry_run=dry_run)
+    required = [f for f in followups if isinstance(f, Followup) and f.required]
+    if required and not dry_run:
+        raise IncompleteMergeError(
+            f"{len(required)} item(s) marked (required) above must be done by hand: until then "
+            "the project does not build or deploy with the settings "
+            "graph-agents-cli-manifest.yaml records."
+        )
+
+
+def _same_file(a: pathlib.Path, b: pathlib.Path) -> bool:
+    try:
+        return a.read_bytes() == b.read_bytes()
+    except OSError:
+        return False
+
+
+def _sidecar_path(project_dir: pathlib.Path, relative_path: str, source: pathlib.Path) -> str:
+    """``<file>.new`` (or ``.new.2``, ...): a free name, or one already holding ``source``."""
+    candidate = f"{relative_path}.new"
+    number = 1
+    while (project_dir / candidate).exists() and not _same_file(project_dir / candidate, source):
+        number += 1
+        candidate = f"{relative_path}.new.{number}"
+    return candidate
+
+
+def _kept_conflict_followups(
+    conflicts: list[FileCompareResult],
+    *,
+    project_dir: pathlib.Path,
+    old_template_dir: pathlib.Path,
+    new_template_dir: pathlib.Path,
+    dry_run: bool,
+    prefer_new: bool,
+) -> list[Followup]:
+    """What is left for each conflict that kept the developer's version (enhance).
+
+    Every difference between the two snapshots of an enhance comes from the
+    settings change, so a kept conflict is part of that change that did not
+    happen: its template diff is listed. A file that defines the image cannot be
+    left behind (it would build the old settings): the template's version is
+    written next to it as ``<file>.new`` and the item is required.
+    """
+    from .merge3 import template_diff
+
+    items: list[Followup] = []
+    for result in conflicts:
+        current = project_dir / result.path
+        new_file = new_template_dir / result.path
+        if dry_run and prefer_new:
+            continue
+        if not dry_run and new_file.exists() and _same_file(current, new_file):
+            continue  # resolved in favour of the new version
+        if not new_file.exists():
+            items.append(
+                Followup(
+                    f"{result.path}: you edited it and the new settings no longer use it; it "
+                    "was kept, delete it if nothing needs it"
+                )
+            )
+            continue
+        if is_image_definition(result.path):
+            sidecar = _sidecar_path(project_dir, result.path, new_file)
+            if not dry_run:
+                copy_file(new_file, project_dir / sidecar)
+            verb = "will be" if dry_run else "was"
+            items.append(
+                Followup(
+                    f"{result.path}: your edited version was kept, and it builds the image for "
+                    f"the old settings. The template's {result.path} for the new settings {verb} "
+                    f"written to {sidecar}: carry your edits over to it, then replace "
+                    f"{result.path} with it (and delete {sidecar}).",
+                    required=True,
+                )
+            )
+            continue
+        old_file = old_template_dir / result.path
+        old_text = (
+            old_file.read_text(encoding="utf-8", errors="replace") if old_file.exists() else ""
+        )
+        new_text = new_file.read_text(encoding="utf-8", errors="replace")
+        items.append(
+            Followup(
+                f"{result.path}: you edited it and the new settings change it too; your version "
+                "was kept. Apply the template's change by hand:\n"
+                + template_diff(old_text, new_text, result.path)
+            )
+        )
+    return items
+
+
+def run_three_way_merge(
+    *,
+    project_dir: pathlib.Path,
+    project_name: str,
+    agent_directory: str,
+    language: str,
+    old_args: list[str],
+    new_args: list[str],
+    old_version: str | None = None,
+    baseline: Baseline = "authentic",
+    old_source: BaselineSource | None = None,
+    auto_approve: bool,
+    dry_run: bool,
+    prefer_new: bool = False,
+    interactive: bool = False,
+    operation_label: str = "upgrade",
+    pre_apply_hook: Callable[[pathlib.Path], bool] | None = None,
+    post_apply_hook: Callable[[pathlib.Path, str], list[str | Followup] | None] | None = None,
+    merge_config: bool = False,
+    snapshot_check: Callable[[pathlib.Path, pathlib.Path], None] | None = None,
+) -> bool:
+    """Shared 3-way merge pipeline used by both *upgrade* and *enhance*.
+
+    Generates old and new template snapshots, compares every file against
+    the current project, displays the diff summary, and applies changes.
+
+    Args:
+        project_dir: Resolved path to the user's project.
+        project_name: Name used when generating the template.
+        agent_directory: Subdirectory containing agent code (e.g. "app").
+        language: Project language ("python").
+        old_args: CLI args for re-creating the *old* template snapshot.
+        new_args: CLI args for re-creating the *new* template snapshot.
+        old_version: If set, the prior CLI version that renders the old snapshot.
+        baseline: "authentic" (default) stops when ``old_version`` cannot be
+            fetched; "current" renders the old snapshot with the current templates.
+        old_source: The build that renders the old snapshot, when one is named
+            (it wins over ``old_version``'s release; authentic baseline only).
+        auto_approve: Auto-apply non-conflicting changes without prompts.
+        dry_run: Preview changes without writing anything.
+        prefer_new: Resolve conflicts in favour of the new template.
+        interactive: Allow interactive conflict-resolution prompts.
+        operation_label: Human-readable verb for prompt/log text.
+        pre_apply_hook: Callback invoked before files are written; return False to abort.
+        post_apply_hook: Callback invoked after files are written (and deps merged);
+            it may return follow-up items for the developer, printed at the end.
+        merge_config: Merge the config files the new settings re-render
+            (``upgrade.STRUCTURAL_CONFIG_FILES``) instead of skipping them, and
+            list what every kept conflict leaves undone (enhance).
+        snapshot_check: Called with the old and new snapshot directories once
+            both exist, before anything is compared; it may raise a
+            ``click.ClickException`` to stop with the project unchanged.
+
+    Returns:
+        True if the pipeline completed (changes applied, user cancelled, or
+        nothing to do). False if a template snapshot could not be generated;
+        the project was not modified.
+
+    Raises:
+        IncompleteMergeError: changes were applied, but a follow-up marked
+            required is left (an image definition that kept the old settings,
+            dependency changes that could not be written, or whatever the
+            post-apply hook marks required). Never raised under ``dry_run``.
+    """
+    same_config = (
+        sorted(old_args) == sorted(new_args) and old_version is None and old_source is None
+    )
+    baseline_label = f" {BASELINE_CURRENT_LABEL}" if baseline == "current" and old_version else ""
+
+    temp_base = pathlib.Path(tempfile.mkdtemp(prefix=f"gacli_{operation_label}_"))
+    old_template_dir = temp_base / "old"
+    new_template_dir = temp_base / "new"
+
+    try:
+        console.print()
+        console.print("[dim]Generating templates for comparison...[/dim]")
+
+        if same_config:
+            # Identical args: generate once, reuse for both.
+            console.print("[dim]  - Template...[/dim]")
+            if not run_create_command(old_args, old_template_dir, project_name):
+                console.print("[bold red]Error:[/bold red] Failed to generate template")
+                return False
+            old_template_project = old_template_dir / project_name
+            new_template_project = old_template_project
+        else:
+            console.print("[dim]  - Old template...[/dim]")
+            if not run_create_command(
+                old_args, old_template_dir, project_name, old_version, baseline, old_source
+            ):
+                console.print(
+                    "[bold red]Error:[/bold red] Failed to generate the old template snapshot"
+                )
+                return False
+
+            console.print("[dim]  - New template...[/dim]")
+            if not run_create_command(new_args, new_template_dir, project_name):
+                console.print("[bold red]Error:[/bold red] Failed to generate new template")
+                return False
+
+            old_template_project = old_template_dir / project_name
+            new_template_project = new_template_dir / project_name
+
+        if snapshot_check is not None:
+            snapshot_check(old_template_project, new_template_project)
+
+        console.print()
+
+        console.print("[dim]Comparing files...[/dim]")
+        results = compare_all_files(
+            project_dir,
+            old_template_project,
+            new_template_project,
+            agent_directory,
+            merge_config=merge_config,
+        )
+        groups = group_results_by_action(results)
+        followups: list[str | Followup] = [r.followup for r in results if r.followup]
+
+        dep_resolutions: list[DependencyResolution] = []
+        merge_dependencies = MERGE_DEPENDENCY_HANDLERS.get(language)
+        if merge_dependencies is None:
+            logging.warning(
+                "Dependency merging isn't supported for %s projects; your "
+                "dependency manifest was left unchanged. Review it manually "
+                "after the %s.",
+                language,
+                operation_label,
+            )
+        else:
+            try:
+                dep_resolutions = merge_dependencies(
+                    project_dir, old_template_project, new_template_project
+                )
+            except DependencyReadError as e:
+                logging.warning(
+                    "Skipping dependency merge: %s. Review your dependency manifest "
+                    "manually after the %s.",
+                    e,
+                    operation_label,
+                )
+
+        console.print()
+
+        display_results(
+            groups,
+            dep_resolutions,
+            dry_run,
+            baseline_current_of=old_version if baseline == "current" else None,
+        )
+
+        total_changes = (
+            len(groups["auto_update"])
+            + len(groups["new"])
+            + len(groups["removed"])
+            + len(groups["conflict"])
+            + len(groups["merge"])
+        )
+        has_dep_changes = any(r.status != "unchanged" for r in dep_resolutions)
+        if total_changes == 0 and not has_dep_changes:
+            if post_apply_hook and not dry_run:
+                followups.extend(post_apply_hook(project_dir, language) or [])
+            console.print(f"[bold green]✅[/bold green] No changes needed!{baseline_label}")
+            _finish(followups, dry_run=dry_run)
+            return True
+
+        if interactive and not dry_run:
+            prompt_text = f"\nProceed with {operation_label}?"
+            if groups["conflict"]:
+                prompt_text = "\nProceed? (you'll resolve conflicts next)"
+            proceed = Prompt.ask(
+                prompt_text,
+                choices=["y", "n"],
+                case_sensitive=False,
+                default="y",
+            ).lower()
+            if proceed != "y":
+                console.print(f"[yellow]{operation_label.capitalize()} cancelled.[/yellow]")
+                return True
+
+        if pre_apply_hook and not dry_run:
+            if not pre_apply_hook(project_dir):
+                return True  # hook signalled abort (e.g. user cancelled backup)
+
+        counts = apply_changes(
+            groups=groups,
+            project_dir=project_dir,
+            new_template_dir=new_template_project,
+            auto_approve=auto_approve,
+            dry_run=dry_run,
+            prefer_new=prefer_new,
+            interactive=interactive,
+            old_template_dir=old_template_project,
+        )
+
+        if merge_config:
+            followups.extend(
+                _kept_conflict_followups(
+                    groups["conflict"],
+                    project_dir=project_dir,
+                    old_template_dir=old_template_project,
+                    new_template_dir=new_template_project,
+                    dry_run=dry_run,
+                    prefer_new=prefer_new,
+                )
+            )
+
+        write_dependencies = WRITE_DEPENDENCY_HANDLERS.get(language)
+        if not dry_run and has_dep_changes and write_dependencies is not None:
+            if write_dependencies(project_dir, dep_resolutions):
+                console.print(
+                    "[dim] Dependencies updated; run [bold]graph-agents-cli install[/bold] "
+                    "to install the new versions.[/dim]"
+                )
+                if merge_config:
+                    followups.append(
+                        Followup(
+                            "Run `graph-agents-cli install` to bring uv.lock (and .venv) up to "
+                            "date with the new dependencies: the image installs exactly what "
+                            "uv.lock pins"
+                        )
+                    )
+            elif merge_config:
+                changes = ", ".join(
+                    f"-{r.name}" if r.status == "removed" else f"+{r.full_name()}"
+                    for r in dep_resolutions
+                    if r.status in ("added", "updated", "removed")
+                )
+                followups.append(
+                    Followup(
+                        "pyproject.toml: the dependency changes for the new settings could not "
+                        f"be written (see the warning above); make them by hand: {changes}",
+                        required=True,
+                    )
+                )
+
+        if post_apply_hook and not dry_run:
+            followups.extend(post_apply_hook(project_dir, language) or [])
+
+        console.print()
+        if dry_run:
+            console.print(
+                "[bold yellow]Dry run complete.[/bold yellow] "
+                f"Run without --dry-run to apply changes.{baseline_label}"
+            )
+        else:
+            console.print(f"  Updated: {counts['updated']} files")
+            if counts["merged"]:
+                console.print(f"  Merged into your edits: {counts['merged']} files")
+            console.print(f"  Added: {counts['added']} files")
+            console.print(f"  Removed: {counts['removed']} files")
+            if counts["conflicts_kept"] or counts["conflicts_updated"]:
+                console.print(
+                    f"  Conflicts: {counts['conflicts_updated']} updated, "
+                    f"{counts['conflicts_kept']} kept yours"
+                )
+            console.print()
+            if any(isinstance(f, Followup) and f.required for f in followups):
+                console.print(
+                    f"[bold yellow]⚠️  {operation_label.capitalize()} applied, with required "
+                    f"steps left for you (below).[/bold yellow]{baseline_label}"
+                )
+            else:
+                console.print(
+                    f"[bold green]✅ {operation_label.capitalize()} complete![/bold green]"
+                    f"{baseline_label}"
+                )
+        _finish(followups, dry_run=dry_run)
+
+        return True
+
+    finally:
+        shutil.rmtree(temp_base, ignore_errors=True)