fastapi-fullstack 0.2.16__tar.gz → 0.2.17__tar.gz

{fastapi_fullstack-0.2.16 → fastapi_fullstack-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fullstack
-Version: 0.2.16
+Version: 0.2.17
 Summary: Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability.
 Project-URL: Homepage, https://github.com/vstorm-co/full-stack-ai-agent-template
 Project-URL: Documentation, https://github.com/vstorm-co/full-stack-ai-agent-template#readme
@@ -25,19 +25,21 @@ Requires-Dist: click>=8.3.3
 Requires-Dist: cookiecutter>=2.7.0
 Requires-Dist: email-validator>=2.3.0
 Requires-Dist: httpx>=0.28.1
+Requires-Dist: packaging>=24.0
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: pydantic>=2.13.0
 Requires-Dist: pytest-asyncio>=1.3.0
 Requires-Dist: pytest>=9.0.3
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=15.0.0
+Requires-Dist: ruff>=0.14.0
 Requires-Dist: stripe>=15.1.0
 Requires-Dist: taskiq>=0.12.4
 Provides-Extra: dev
 Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.0; extra == 'dev'
-Requires-Dist: ruff>=0.14.0; extra == 'dev'
 Requires-Dist: ty>=0.0.31; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.7.0; extra == 'docs'
@@ -210,6 +212,39 @@ fastapi-fullstack create my_ai_app --minimal
 
 </details>
 
+### Keeping your project up to date
+
+Your project doesn't get stranded on the template version you generated from. Pull the
+latest template improvements into your existing project with a real 3-way merge — your
+customizations are preserved, conflicts are left for you to resolve in your IDE, and the
+whole thing lands on a dedicated branch so it's fully reversible:
+
+```bash
+make upgrade-dry-run     # preview what would change (no changes made)
+make upgrade             # apply on a `template-upgrade/v…` branch
+# resolve any conflicts in your IDE's 3-way merge editor, then:
+make upgrade-finalize    # bump the manifest to the new version
+```
+
+Files only you changed are kept, files only the template changed are updated, and new
+features/migrations are pulled in. By default an upgrade keeps your existing feature set —
+to also adopt optional features added since your version, use:
+
+```bash
+make upgrade-new-features   # prompts Yes/No for each new optional feature
+```
+
+One-off flags (e.g. pinning a target version) go through `ARGS`, and you can always call
+the CLI directly instead of `make`:
+
+```bash
+make upgrade ARGS=--to=0.3.0
+uvx fastapi-fullstack@latest upgrade --with-new-features
+```
+
+See the [version-upgrade guide](docs/guides/version-upgrade.md) for the full walkthrough
+(including projects generated before upgrade support existed).
+
 ### Environments
 
 | `make` target | Compose file | When to use |

{fastapi_fullstack-0.2.16 → fastapi_fullstack-0.2.17}/README.md

@@ -163,6 +163,39 @@ fastapi-fullstack create my_ai_app --minimal
 
 </details>
 
+### Keeping your project up to date
+
+Your project doesn't get stranded on the template version you generated from. Pull the
+latest template improvements into your existing project with a real 3-way merge — your
+customizations are preserved, conflicts are left for you to resolve in your IDE, and the
+whole thing lands on a dedicated branch so it's fully reversible:
+
+```bash
+make upgrade-dry-run     # preview what would change (no changes made)
+make upgrade             # apply on a `template-upgrade/v…` branch
+# resolve any conflicts in your IDE's 3-way merge editor, then:
+make upgrade-finalize    # bump the manifest to the new version
+```
+
+Files only you changed are kept, files only the template changed are updated, and new
+features/migrations are pulled in. By default an upgrade keeps your existing feature set —
+to also adopt optional features added since your version, use:
+
+```bash
+make upgrade-new-features   # prompts Yes/No for each new optional feature
+```
+
+One-off flags (e.g. pinning a target version) go through `ARGS`, and you can always call
+the CLI directly instead of `make`:
+
+```bash
+make upgrade ARGS=--to=0.3.0
+uvx fastapi-fullstack@latest upgrade --with-new-features
+```
+
+See the [version-upgrade guide](docs/guides/version-upgrade.md) for the full walkthrough
+(including projects generated before upgrade support existed).
+
 ### Environments
 
 | `make` target | Compose file | When to use |

fastapi_fullstack-0.2.17/UPGRADES.yaml

@@ -0,0 +1,21 @@
+# Structural metadata for `fastapi-fullstack upgrade` (renames, removals, manual steps).
+# See docs/guides/version-upgrade.md — "For template maintainers". One block per release.
+#
+# Schema (all keys optional except `version`):
+#
+# - version: "0.2.15"
+#   renames:
+#     - from: "backend/app/core/config.py"
+#       to:   "backend/app/core/settings.py"
+#   variable_renames:
+#     - from: "use_pgvector"
+#       to:   "vector_store"
+#       value_map: { "true": "pgvector" }
+#   removed:
+#     - "backend/app/legacy_auth.py"
+#   breaking:
+#     - "JWT secret env var renamed SECRET_KEY → AUTH_SECRET_KEY."
+#   manual_steps:
+#     - "Run `alembic upgrade head` (new billing tables)."
+
+[]

{fastapi_fullstack-0.2.16 → fastapi_fullstack-0.2.17}/fastapi_gen/cli.py

@@ -1,8 +1,10 @@
 """CLI interface for Full-Stack AI Agent Template Generator."""
 
+import subprocess
 from pathlib import Path
 
 import click
+from click.core import ParameterSource
 from rich.console import Console
 
 from . import __version__
@@ -490,6 +492,12 @@ def new(output: Path | None, no_input: bool, name: str | None, minimal: bool) ->
     default=False,
     help="Enable the deep research agent (TODO planner + subagents + context manager, PydanticAI only)",
 )
+@click.option(
+    "--mcp-client",
+    is_flag=True,
+    default=False,
+    help="Enable the MCP client — connect external MCP servers as agent tools (PydanticAI only)",
+)
 @click.option("--session-management", is_flag=True, help="Enable session management")
 @click.option(
     "--reverse-proxy",
@@ -774,6 +782,7 @@ def create(
     code_execution: bool,
     skills: bool,
     deep_research: bool,
+    mcp_client: bool,
     session_management: bool,
     reverse_proxy: str,
     kubernetes: bool,
@@ -1195,6 +1204,7 @@ def create(
                 enable_code_execution=code_execution,
                 enable_skills=skills,
                 enable_deep_research=deep_research,
+                enable_mcp_client=mcp_client,
                 enable_session_management=session_management,
                 reverse_proxy=_rp_map[reverse_proxy],
                 enable_kubernetes=kubernetes,
@@ -1463,6 +1473,138 @@ def templates() -> None:
     console.print("  --frontend-port N  Frontend port (default: 3000)")
 
 
+_PATH_OPTION = click.option(
+    "--path",
+    "project_path",
+    default=".",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True, path_type=Path),
+    help="Project directory (default: current directory).",
+)
+
+
+def _git_error_message(exc: subprocess.CalledProcessError) -> str:
+    """Turn a failed git call into a message that keeps its stderr.
+
+    Every git call in the upgrade runs with ``check=True`` and captured output, so a
+    raw ``CalledProcessError`` would surface only the exit status and bury the actual
+    reason (bad git version, unicode pathspec, …) in the swallowed stderr.
+    """
+    cmd = exc.cmd
+    printable = " ".join(map(str, cmd)) if isinstance(cmd, (list, tuple)) else str(cmd)
+    detail = exc.stderr
+    if isinstance(detail, bytes):
+        detail = detail.decode("utf-8", "replace")
+    message = f"git command failed: {printable}"
+    if detail and detail.strip():
+        message += f"\n{detail.strip()}"
+    return message
+
+
+@cli.group(invoke_without_command=True)
+@_PATH_OPTION
+@click.option("--to", "to_version", default=None, help="Target version (default: latest).")
+@click.option("--dry-run", is_flag=True, help="Preview the upgrade without changing anything.")
+@click.option(
+    "--with-new-features",
+    is_flag=True,
+    help="Prompt to adopt optional features introduced since your version.",
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Recreate the upgrade branch if it exists, and overwrite colliding untracked files.",
+)
+@click.pass_context
+def upgrade(
+    ctx: click.Context,
+    project_path: Path,
+    to_version: str | None,
+    dry_run: bool,
+    with_new_features: bool,
+    force: bool,
+) -> None:
+    """Pull the latest template improvements into an existing project.
+
+    Run from inside a generated project. With no subcommand this performs the
+    upgrade; ``upgrade finalize`` bumps the manifest once conflicts are resolved.
+    """
+    if ctx.invoked_subcommand is not None:
+        # --path has a default, so "was it typed?" needs click's parameter source
+        # rather than a None check — otherwise `upgrade --path X finalize` silently
+        # finalizes the current directory instead of X.
+        path_given = ctx.get_parameter_source("project_path") is not ParameterSource.DEFAULT
+        misplaced = [
+            name
+            for name, given in (
+                ("--path", path_given),
+                ("--to", to_version is not None),
+                ("--dry-run", dry_run),
+                ("--with-new-features", with_new_features),
+                ("--force", force),
+            )
+            if given
+        ]
+        if misplaced:
+            # --path needs the opposite advice to the rest: the subcommands carry their
+            # own --path, so it moves *after* the subcommand. Telling the user to put it
+            # before (where they already had it, since that is what lands here) sends
+            # them in a circle, and dropping it would finalize the wrong directory.
+            fix = (
+                f"Use `upgrade {ctx.invoked_subcommand} --path ...` — the subcommand has "
+                "its own --path."
+                if misplaced == ["--path"]
+                else "Drop it, or run `upgrade` without a subcommand."
+            )
+            raise click.UsageError(
+                f"{', '.join(misplaced)} applies to `upgrade`, not "
+                f"`upgrade {ctx.invoked_subcommand}`. {fix}"
+            )
+        return
+
+    from .upgrade.runner import UpgradeError, run_upgrade
+
+    try:
+        run_upgrade(
+            project_path,
+            to_version=to_version,
+            dry_run=dry_run,
+            with_new_features=with_new_features,
+            force=force,
+        )
+    except subprocess.CalledProcessError as exc:
+        raise click.ClickException(_git_error_message(exc)) from exc
+    except (UpgradeError, FileNotFoundError, RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@upgrade.command("finalize")
+@_PATH_OPTION
+def upgrade_finalize(project_path: Path) -> None:
+    """Bump the manifest to the new version after resolving conflicts."""
+    from .upgrade.runner import UpgradeError, run_finalize
+
+    try:
+        run_finalize(project_path)
+    except subprocess.CalledProcessError as exc:
+        raise click.ClickException(_git_error_message(exc)) from exc
+    except (UpgradeError, FileNotFoundError, RuntimeError, ValueError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+@upgrade.command("recover")
+@_PATH_OPTION
+def upgrade_recover(project_path: Path) -> None:
+    """Reconstruct a candidate manifest for a project generated before manifests."""
+    from .upgrade.runner import run_recover
+
+    try:
+        run_recover(project_path)
+    except subprocess.CalledProcessError as exc:  # pragma: no cover
+        raise click.ClickException(_git_error_message(exc)) from exc
+    except (FileNotFoundError, RuntimeError) as exc:  # pragma: no cover
+        raise click.ClickException(str(exc)) from exc
+
+
 def main() -> None:
     """Main entry point."""
     cli()

{fastapi_fullstack-0.2.16 → fastapi_fullstack-0.2.17}/fastapi_gen/config.py

@@ -328,6 +328,7 @@ class ProjectConfig(BaseModel):
     enable_deep_research: bool = False
     enable_todo: bool = False
     enable_subagents: bool = False
+    enable_mcp_client: bool = False
     use_telegram: bool = False
     use_slack: bool = False
     enable_cors: bool = True
@@ -492,6 +493,22 @@ class ProjectConfig(BaseModel):
                 "Quick fix: set --ai-framework pydantic_ai, or drop --deep-research."
             )
 
+        if self.enable_mcp_client and self.ai_framework != AIFrameworkType.PYDANTIC_AI:
+            raise ValueError(
+                "The MCP client requires the PydanticAI framework. "
+                "Quick fix: set --ai-framework pydantic_ai, or drop --mcp-client."
+            )
+        # Defense-in-depth: unreachable today because the only non-Postgres option
+        # (DatabaseType.NONE) is already rejected above ("a database is required"), but
+        # kept so wiring in another backend (e.g. MongoDB) can't silently ship the MCP
+        # client on a store that lacks JSONB + encrypted-token columns.
+        if self.enable_mcp_client and self.database != DatabaseType.POSTGRESQL:  # pragma: no cover
+            raise ValueError(
+                "The MCP client stores per-user connections in PostgreSQL "
+                "(JSONB + encrypted tokens). "
+                "Quick fix: switch to --database postgresql or drop --mcp-client."
+            )
+
         # --no-ai: RAG and websockets require an AI framework
         if not self.use_ai and self.rag_features.enable_rag:
             raise ValueError(
@@ -816,6 +833,7 @@ class ProjectConfig(BaseModel):
             "enable_deep_research": self.enable_deep_research,
             "enable_todo": self.enable_todo,
             "enable_subagents": self.enable_subagents,
+            "enable_mcp_client": self.enable_mcp_client,
             "enable_webhooks": self.enable_webhooks,
             # Legacy fixed values (WebSocket always uses JWT)
             "websocket_auth": "jwt",

{fastapi_fullstack-0.2.16 → fastapi_fullstack-0.2.17}/fastapi_gen/generator.py

@@ -8,6 +8,7 @@ from rich.console import Console
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
 from .config import DatabaseType, FrontendType, ProjectConfig
+from .upgrade import write_manifest
 
 console = Console()
 
@@ -97,6 +98,7 @@ def generate_project(config: ProjectConfig, output_dir: Path | None = None) -> P
                 output_dir=str(output_dir),
                 no_input=True,
             )
+            write_manifest(Path(project_path), context)
         except Exception:
             # Cleanup partial files on failure
             if target_dir.exists():

{fastapi_fullstack-0.2.16 → fastapi_fullstack-0.2.17}/fastapi_gen/prompts.py

@@ -975,6 +975,29 @@ def prompt_deep_research() -> dict[str, bool]:
     }
 
 
+def prompt_mcp_client() -> bool:
+    """Prompt for the MCP client (PydanticAI only)."""
+    console.print()
+    console.print("[bold cyan]MCP Client[/]")
+    console.print(
+        "Let users connect external Model Context Protocol servers (Notion, Linear, "
+        "Jira, Stripe, GitHub, …) as extra agent tools from Settings → Integrations. "
+        "Includes a curated marketplace, per-user connections, OAuth sign-in and "
+        "token/SSE + streamable-HTTP transports."
+    )
+    console.print()
+
+    return cast(
+        bool,
+        _check_cancelled(
+            questionary.confirm(
+                "Enable the MCP client (PydanticAI only)?",
+                default=False,
+            ).ask()
+        ),
+    )
+
+
 def prompt_langsmith() -> bool:
     """Prompt for LangSmith observability."""
     return cast(
@@ -1493,6 +1516,7 @@ def run_interactive_prompts() -> ProjectConfig:
         "enable_code_execution": False,
         "enable_skills": False,
         "enable_deep_research": False,
+        "enable_mcp_client": False,
         "rag_features": RAGFeatures(),
         "orm_type": OrmType.SQLALCHEMY,
         "sandbox_backend": "state",
@@ -1672,6 +1696,12 @@ def run_interactive_prompts() -> ProjectConfig:
             state["enable_todo"] = False
             state["enable_subagents"] = False
 
+    def step_mcp_client() -> None:
+        if state.get("ai_framework") == AIFrameworkType.PYDANTIC_AI.value:
+            state["enable_mcp_client"] = prompt_mcp_client()
+        else:
+            state["enable_mcp_client"] = False
+
     def step_langsmith() -> None:
         if state["ai_framework"] in (
             AIFrameworkType.LANGCHAIN,
@@ -1734,6 +1764,7 @@ def run_interactive_prompts() -> ProjectConfig:
         ("Code Execution", step_code_execution),
         ("Skills System", step_skills),
         ("Deep Research", step_deep_research),
+        ("MCP Client", step_mcp_client),
         ("Observability (Logfire)", step_logfire),
         ("Agent Sandbox", step_sandbox_backend),
         ("LLM Provider", step_llm_provider),
@@ -1786,6 +1817,7 @@ def run_interactive_prompts() -> ProjectConfig:
     enable_code_execution = state["enable_code_execution"]
     enable_skills = state["enable_skills"]
     enable_deep_research = state["enable_deep_research"]
+    enable_mcp_client = state["enable_mcp_client"]
     rag_features = state["rag_features"]
     enable_langsmith = state["enable_langsmith"]
     use_telegram = state["use_telegram"]
@@ -1844,6 +1876,7 @@ def run_interactive_prompts() -> ProjectConfig:
         enable_code_execution=enable_code_execution,
         enable_skills=enable_skills,
         enable_deep_research=enable_deep_research,
+        enable_mcp_client=enable_mcp_client,
         use_telegram=use_telegram,
         use_slack=use_slack,
         rate_limit_requests=rate_limit_requests,

fastapi_fullstack-0.2.17/fastapi_gen/upgrade/__init__.py

@@ -0,0 +1,25 @@
+"""Version-upgrade tooling.
+
+Lets an already-generated project pull in improvements from a newer template
+version via a 3-way merge (see docs/guides/version-upgrade.md). This
+subpackage keeps all upgrade logic out of generated projects — they carry only
+the manifest (``.fastapi-fullstack.json``) plus a thin Makefile shim.
+"""
+
+from .manifest import (
+    MANIFEST_FILENAME,
+    build_manifest,
+    compute_context_hash,
+    read_manifest,
+    redact_secrets,
+    write_manifest,
+)
+
+__all__ = [
+    "MANIFEST_FILENAME",
+    "build_manifest",
+    "compute_context_hash",
+    "read_manifest",
+    "redact_secrets",
+    "write_manifest",
+]

fastapi_fullstack-0.2.17/fastapi_gen/upgrade/_render_worker.py

@@ -0,0 +1,43 @@
+"""Subprocess entry point that renders a cookiecutter template.
+
+Run as ``python -m fastapi_gen.upgrade._render_worker <template_dir>
+<context_json> <output_dir>``. It exists as a separate process so the caller
+(:mod:`fastapi_gen.upgrade.render`) can hand it a controlled environment — a
+``PATH`` containing only no-op shims — which the post-gen hook (a grandchild
+process) inherits, neutralizing ``uv lock`` / ``bun install`` / ``ruff`` etc.
+without modifying any released template.
+
+Prints ``RENDERED::<path>`` on success so the parent can capture the output path.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from cookiecutter.main import cookiecutter
+
+_RESULT_PREFIX = "RENDERED::"
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 4:
+        print("usage: _render_worker <template_dir> <context_json> <output_dir>", file=sys.stderr)
+        return 2
+    template_dir, context_file, output_dir = argv[1], argv[2], argv[3]
+    context = json.loads(Path(context_file).read_text(encoding="utf-8"))
+
+    path = cookiecutter(
+        template_dir,
+        no_input=True,
+        extra_context=context,
+        output_dir=output_dir,
+        overwrite_if_exists=True,
+    )
+    print(f"{_RESULT_PREFIX}{path}")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main(sys.argv))

fastapi_fullstack-0.2.17/fastapi_gen/upgrade/classify.py

@@ -0,0 +1,125 @@
+"""Classify every path across BASE / OURS / THEIRS for the upgrade report.
+
+Implements the file-classification matrix. The merge engine (merge.py) decides
+what actually gets written; this module produces the human-facing grouping shown in
+the report so the developer sees *why* each change is proposed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .merge import is_excluded
+
+_MIGRATIONS_MARKER = "alembic/versions/"
+
+
+def _file_hashes(tree: Path) -> dict[str, str]:
+    """Map in-scope repo-relative path → content hash for a rendered tree."""
+    hashes: dict[str, str] = {}
+    for path in tree.rglob("*"):
+        if not path.is_file() or path.is_symlink():
+            continue
+        rel = path.relative_to(tree).as_posix()
+        if is_excluded(rel):
+            continue
+        hashes[rel] = hashlib.sha256(path.read_bytes()).hexdigest()
+    return hashes
+
+
+@dataclass
+class Classification:
+    """Grouped upgrade outcome (each list holds repo-relative paths)."""
+
+    auto_updated: list[str] = field(default_factory=list)
+    client_kept: list[str] = field(default_factory=list)
+    converged: list[str] = field(default_factory=list)
+    auto_merged: list[str] = field(default_factory=list)
+    conflicts: list[str] = field(default_factory=list)
+    new_files: list[str] = field(default_factory=list)
+    new_migrations: list[str] = field(default_factory=list)
+    changed_migrations: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    client_deleted: list[str] = field(default_factory=list)
+    client_only: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+    other: list[str] = field(default_factory=list)
+
+
+def classify_trees(
+    base_dir: Path,
+    ours_dir: Path,
+    theirs_dir: Path,
+    conflicted_paths: set[str],
+) -> Classification:
+    """Classify each path per the classification matrix; conflicts come from the merge."""
+    base, ours, theirs = _file_hashes(base_dir), _file_hashes(ours_dir), _file_hashes(theirs_dir)
+    result = Classification()
+
+    for path in sorted(set(base) | set(ours) | set(theirs)):
+        in_base, in_ours, in_theirs = path in base, path in ours, path in theirs
+        is_migration = _MIGRATIONS_MARKER in path
+
+        if path in conflicted_paths:
+            result.conflicts.append(path)
+            continue
+
+        if not in_base and not in_ours and in_theirs:
+            (result.new_migrations if is_migration else result.new_files).append(path)
+        elif in_base and in_ours and not in_theirs:
+            if base[path] == ours[path]:
+                result.removed.append(path)
+            else:
+                result.auto_merged.append(path)
+        elif not in_base and in_ours and not in_theirs:
+            result.client_only.append(path)
+        elif not in_base and in_ours and in_theirs:
+            if ours[path] == theirs[path]:
+                result.converged.append(path)
+            else:
+                result.auto_merged.append(path)
+        elif in_base and in_ours and in_theirs:
+            b, o, t = base[path], ours[path], theirs[path]
+            if b == o == t:
+                result.unchanged.append(path)
+            elif o == b and t != b:
+                # A migration that already exists has, in all likelihood, already run
+                # against the client's database. Rewriting its body doesn't re-run it —
+                # alembic keys off the revision id — so the file would silently stop
+                # describing the schema it produced. The merge still applies the change
+                # (it lands on a branch, and sometimes a release genuinely fixes a
+                # migration), but it must never be buried in a 30-line "Auto-updates"
+                # list the reader skims.
+                (result.changed_migrations if is_migration else result.auto_updated).append(path)
+            elif t == b and o != b:
+                result.client_kept.append(path)
+            elif o == t and o != b:
+                result.converged.append(path)
+            else:
+                (result.changed_migrations if is_migration else result.auto_merged).append(path)
+        elif in_base and not in_ours and not in_theirs:
+            # Client and template both dropped it. Nothing to do, and nothing to read —
+            # it only ever showed up under "Other changes (review on the branch)", which
+            # sent the reader hunting for a problem that doesn't exist.
+            result.converged.append(path)
+        elif in_base and not in_ours and in_theirs:
+            # The client deleted a file the template still ships. If the template didn't
+            # touch it, git keeps it deleted and there is genuinely nothing to review —
+            # but it is worth naming, because the alternative reading ("the upgrade lost
+            # my file") is exactly what a user fears. A template-side change here is a
+            # modify/delete conflict, so it never reaches this branch.
+            if base[path] == theirs[path]:
+                result.client_deleted.append(path)
+            else:
+                result.auto_merged.append(path)
+        else:
+            # Unreachable: `path` comes from the union of the three trees, so at least
+            # one membership flag is set and the branches above cover all seven states
+            # (test_the_matrix_is_exhaustive pins that). Kept as a catch-all so a future
+            # edit that opens a hole surfaces the path in the report instead of dropping
+            # it silently — the one failure mode a classifier must not have.
+            result.other.append(path)
+
+    return result