Release version 1.2.0

* Treat remote tags as the source of truth by force-fetching tags from *origin*
* Update preview output to reflect the real fetch behavior
* Align unit tests with the new forced tag fetch command

https://chatgpt.com/share/693bdfc3-b8b4-800f-8adc-b1dc63c56a89

.gitignore

@@ -27,6 +27,7 @@ Thumbs.db
 # Nix Cache to speed up tests
 .nix/
 .nix-dev-installed
+flake.lock
 
 # Ignore logs
 *.log

CHANGELOG.md

@@ -1,3 +1,20 @@
+## [1.2.0] - 2025-12-12
+
+* **Release workflow overhaul**
+
+* Introduced a fully structured release workflow with clear phases and safeguards
+* Added preview-first releases with explicit confirmation before execution
+* Automatic handling of *latest* tag when a release is the newest version
+* Optional branch closing after successful releases with interactive confirmation
+* Improved safety by syncing with remote before any changes
+* Clear separation of concerns (workflow, git handling, prompts, versioning)
+
+
+## [1.1.0] - 2025-12-12
+
+* Added *branch drop* for destructive branch deletion and introduced *--force/-f* flags for branch close and branch drop to skip confirmation prompts.
+
+
 ## [1.0.0] - 2025-12-11
 
 * **1.0.0 – Official Stable Release 🎉**

README.md

@@ -1,5 +1,7 @@
 # Package Manager 🤖📦
 
+![PKGMGR Banner](assets/banner.jpg)
+
 [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach)
 [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach)
 [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach)

_requirements.txt

@@ -1,4 +0,0 @@
-# Legacy file used only if pip still installs from requirements.txt.
-# You may delete this file once you switch entirely to pyproject.toml.
-
-PyYAML

flake.lock

@@ -1,27 +0,0 @@
-{
-  "nodes": {
-    "nixpkgs": {
-      "locked": {
-        "lastModified": 1765186076,
-        "narHash": "sha256-hM20uyap1a0M9d344I692r+ik4gTMyj60cQWO+hAYP8=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "addf7cf5f383a3101ecfba091b98d0a1263dc9b8",
-        "type": "github"
-      },
-      "original": {
-        "owner": "NixOS",
-        "ref": "nixos-unstable",
-        "repo": "nixpkgs",
-        "type": "github"
-      }
-    },
-    "root": {
-      "inputs": {
-        "nixpkgs": "nixpkgs"
-      }
-    }
-  },
-  "root": "root",
-  "version": 7
-}

flake.nix

@@ -36,7 +36,7 @@
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "1.0.0";
+            version = "1.2.0";
 
             # Use the git repo as source
             src = ./.;

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "package-manager"
-version = "1.0.0"
+version = "1.2.0"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.11"

src/pkgmgr/actions/branch/__init__.py

@@ -1,235 +1,14 @@
-# pkgmgr/actions/branch/__init__.py
-#!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-
 """
-High-level helpers for branch-related operations.
+Public API for branch actions.
-
-This module encapsulates the actual Git logic so the CLI layer
-(pkgmgr.cli.commands.branch) stays thin and testable.
 """
 
-from __future__ import annotations
+from .open_branch import open_branch
+from .close_branch import close_branch
+from .drop_branch import drop_branch
 
-from typing import Optional
+__all__ = [
-
+    "open_branch",
-from pkgmgr.core.git import run_git, GitError, get_current_branch
+    "close_branch",
-
+    "drop_branch",
-
+]
-# ---------------------------------------------------------------------------
-# Branch creation (open)
-# ---------------------------------------------------------------------------
-
-def open_branch(
-    name: Optional[str],
-    base_branch: str = "main",
-    fallback_base: str = "master",
-    cwd: str = ".",
-) -> None:
-    """
-    Create and push a new feature branch on top of a base branch.
-
-    The base branch is resolved by:
-        1. Trying 'base_branch' (default: 'main')
-        2. Falling back to 'fallback_base' (default: 'master')
-
-    Steps:
-        1) git fetch origin
-        2) git checkout <resolved_base>
-        3) git pull origin <resolved_base>
-        4) git checkout -b <name>
-        5) git push -u origin <name>
-
-    If `name` is None or empty, the user is prompted to enter one.
-    """
-
-    # Request name interactively if not provided
-    if not name:
-        name = input("Enter new branch name: ").strip()
-
-    if not name:
-        raise RuntimeError("Branch name must not be empty.")
-
-    # Resolve which base branch to use (main or master)
-    resolved_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
-
-    # 1) Fetch from origin
-    try:
-        run_git(["fetch", "origin"], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to fetch from origin before creating branch {name!r}: {exc}"
-        ) from exc
-
-    # 2) Checkout base branch
-    try:
-        run_git(["checkout", resolved_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to checkout base branch {resolved_base!r}: {exc}"
-        ) from exc
-
-    # 3) Pull latest changes for base branch
-    try:
-        run_git(["pull", "origin", resolved_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to pull latest changes for base branch {resolved_base!r}: {exc}"
-        ) from exc
-
-    # 4) Create new branch
-    try:
-        run_git(["checkout", "-b", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to create new branch {name!r} from base {resolved_base!r}: {exc}"
-        ) from exc
-
-    # 5) Push new branch to origin
-    try:
-        run_git(["push", "-u", "origin", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to push new branch {name!r} to origin: {exc}"
-        ) from exc
-
-
-# ---------------------------------------------------------------------------
-# Base branch resolver (shared by open/close)
-# ---------------------------------------------------------------------------
-
-def _resolve_base_branch(
-    preferred: str,
-    fallback: str,
-    cwd: str,
-) -> str:
-    """
-    Resolve the base branch to use.
-
-    Try `preferred` first (default: main),
-    fall back to `fallback` (default: master).
-
-    Raise RuntimeError if neither exists.
-    """
-    for candidate in (preferred, fallback):
-        try:
-            run_git(["rev-parse", "--verify", candidate], cwd=cwd)
-            return candidate
-        except GitError:
-            continue
-
-    raise RuntimeError(
-        f"Neither {preferred!r} nor {fallback!r} exist in this repository."
-    )
-
-
-# ---------------------------------------------------------------------------
-# Branch closing (merge + deletion)
-# ---------------------------------------------------------------------------
-
-def close_branch(
-    name: Optional[str],
-    base_branch: str = "main",
-    fallback_base: str = "master",
-    cwd: str = ".",
-) -> None:
-    """
-    Merge a feature branch into the base branch and delete it afterwards.
-
-    Steps:
-        1) Determine the branch name (argument or current branch)
-        2) Resolve base branch (main/master)
-        3) Ask for confirmation
-        4) git fetch origin
-        5) git checkout <base>
-        6) git pull origin <base>
-        7) git merge --no-ff <name>
-        8) git push origin <base>
-        9) Delete branch locally
-       10) Delete branch on origin (best effort)
-    """
-
-    # 1) Determine which branch should be closed
-    if not name:
-        try:
-            name = get_current_branch(cwd=cwd)
-        except GitError as exc:
-            raise RuntimeError(f"Failed to detect current branch: {exc}") from exc
-
-    if not name:
-        raise RuntimeError("Branch name must not be empty.")
-
-    # 2) Resolve base branch
-    target_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
-
-    if name == target_base:
-        raise RuntimeError(
-            f"Refusing to close base branch {target_base!r}. "
-            "Please specify a feature branch."
-        )
-
-    # 3) Ask user for confirmation
-    prompt = (
-        f"Merge branch '{name}' into '{target_base}' and delete it afterwards? "
-        "(y/N): "
-    )
-    answer = input(prompt).strip().lower()
-    if answer != "y":
-        print("Aborted closing branch.")
-        return
-
-    # 4) Fetch from origin
-    try:
-        run_git(["fetch", "origin"], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to fetch from origin before closing branch {name!r}: {exc}"
-        ) from exc
-
-    # 5) Checkout base
-    try:
-        run_git(["checkout", target_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to checkout base branch {target_base!r}: {exc}"
-        ) from exc
-
-    # 6) Pull latest base state
-    try:
-        run_git(["pull", "origin", target_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to pull latest changes for base branch {target_base!r}: {exc}"
-        ) from exc
-
-    # 7) Merge the feature branch
-    try:
-        run_git(["merge", "--no-ff", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to merge branch {name!r} into {target_base!r}: {exc}"
-        ) from exc
-
-    # 8) Push updated base
-    try:
-        run_git(["push", "origin", target_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to push base branch {target_base!r} after merge: {exc}"
-        ) from exc
-
-    # 9) Delete branch locally
-    try:
-        run_git(["branch", "-d", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to delete local branch {name!r}: {exc}"
-        ) from exc
-
-    # 10) Delete branch on origin (best effort)
-    try:
-        run_git(["push", "origin", "--delete", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Branch {name!r} was deleted locally, but remote deletion failed: {exc}"
-        ) from exc

src/pkgmgr/actions/branch/close_branch.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Optional
+from pkgmgr.core.git import run_git, GitError, get_current_branch
+from .utils import _resolve_base_branch
+
+
+def close_branch(
+    name: Optional[str],
+    base_branch: str = "main",
+    fallback_base: str = "master",
+    cwd: str = ".",
+    force: bool = False,
+) -> None:
+    """
+    Merge a feature branch into the base branch and delete it afterwards.
+    """
+
+    # Determine branch name
+    if not name:
+        try:
+            name = get_current_branch(cwd=cwd)
+        except GitError as exc:
+            raise RuntimeError(f"Failed to detect current branch: {exc}") from exc
+
+    if not name:
+        raise RuntimeError("Branch name must not be empty.")
+
+    target_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
+
+    if name == target_base:
+        raise RuntimeError(
+            f"Refusing to close base branch {target_base!r}. "
+            "Please specify a feature branch."
+        )
+
+    # Confirmation
+    if not force:
+        answer = input(
+            f"Merge branch '{name}' into '{target_base}' and delete it afterwards? (y/N): "
+        ).strip().lower()
+        if answer != "y":
+            print("Aborted closing branch.")
+            return
+
+    # Fetch
+    try:
+        run_git(["fetch", "origin"], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to fetch from origin before closing branch {name!r}: {exc}"
+        ) from exc
+
+    # Checkout base
+    try:
+        run_git(["checkout", target_base], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to checkout base branch {target_base!r}: {exc}"
+        ) from exc
+
+    # Pull latest
+    try:
+        run_git(["pull", "origin", target_base], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to pull latest changes for base branch {target_base!r}: {exc}"
+        ) from exc
+
+    # Merge
+    try:
+        run_git(["merge", "--no-ff", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to merge branch {name!r} into {target_base!r}: {exc}"
+        ) from exc
+
+    # Push result
+    try:
+        run_git(["push", "origin", target_base], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to push base branch {target_base!r} after merge: {exc}"
+        ) from exc
+
+    # Delete local
+    try:
+        run_git(["branch", "-d", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to delete local branch {name!r}: {exc}"
+        ) from exc
+
+    # Delete remote
+    try:
+        run_git(["push", "origin", "--delete", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Branch {name!r} deleted locally, but remote deletion failed: {exc}"
+        ) from exc

src/pkgmgr/actions/branch/drop_branch.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Optional
+from pkgmgr.core.git import run_git, GitError, get_current_branch
+from .utils import _resolve_base_branch
+
+
+def drop_branch(
+    name: Optional[str],
+    base_branch: str = "main",
+    fallback_base: str = "master",
+    cwd: str = ".",
+    force: bool = False,
+) -> None:
+    """
+    Delete a branch locally and remotely without merging.
+    """
+
+    if not name:
+        try:
+            name = get_current_branch(cwd=cwd)
+        except GitError as exc:
+            raise RuntimeError(f"Failed to detect current branch: {exc}") from exc
+
+    if not name:
+        raise RuntimeError("Branch name must not be empty.")
+
+    target_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
+
+    if name == target_base:
+        raise RuntimeError(
+            f"Refusing to drop base branch {target_base!r}. It cannot be deleted."
+        )
+
+    # Confirmation
+    if not force:
+        answer = input(
+            f"Delete branch '{name}' locally and on origin? This is destructive! (y/N): "
+        ).strip().lower()
+        if answer != "y":
+            print("Aborted dropping branch.")
+            return
+
+    # Local delete
+    try:
+        run_git(["branch", "-d", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(f"Failed to delete local branch {name!r}: {exc}") from exc
+
+    # Remote delete
+    try:
+        run_git(["push", "origin", "--delete", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Branch {name!r} was deleted locally, but remote deletion failed: {exc}"
+        ) from exc

src/pkgmgr/actions/branch/open_branch.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Optional
+from pkgmgr.core.git import run_git, GitError
+from .utils import _resolve_base_branch
+
+
+def open_branch(
+    name: Optional[str],
+    base_branch: str = "main",
+    fallback_base: str = "master",
+    cwd: str = ".",
+) -> None:
+    """
+    Create and push a new feature branch on top of a base branch.
+    """
+
+    # Request name interactively if not provided
+    if not name:
+        name = input("Enter new branch name: ").strip()
+
+    if not name:
+        raise RuntimeError("Branch name must not be empty.")
+
+    resolved_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
+
+    # 1) Fetch from origin
+    try:
+        run_git(["fetch", "origin"], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to fetch from origin before creating branch {name!r}: {exc}"
+        ) from exc
+
+    # 2) Checkout base branch
+    try:
+        run_git(["checkout", resolved_base], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to checkout base branch {resolved_base!r}: {exc}"
+        ) from exc
+
+    # 3) Pull latest changes
+    try:
+        run_git(["pull", "origin", resolved_base], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to pull latest changes for base branch {resolved_base!r}: {exc}"
+        ) from exc
+
+    # 4) Create new branch
+    try:
+        run_git(["checkout", "-b", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to create new branch {name!r} from base {resolved_base!r}: {exc}"
+        ) from exc
+
+    # 5) Push new branch
+    try:
+        run_git(["push", "-u", "origin", name], cwd=cwd)
+    except GitError as exc:
+        raise RuntimeError(
+            f"Failed to push new branch {name!r} to origin: {exc}"
+        ) from exc

src/pkgmgr/actions/branch/utils.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+from pkgmgr.core.git import run_git, GitError
+
+
+def _resolve_base_branch(
+    preferred: str,
+    fallback: str,
+    cwd: str,
+) -> str:
+    """
+    Resolve the base branch to use.
+
+    Try `preferred` first (default: main),
+    fall back to `fallback` (default: master).
+
+    Raise RuntimeError if neither exists.
+    """
+    for candidate in (preferred, fallback):
+        try:
+            run_git(["rev-parse", "--verify", candidate], cwd=cwd)
+            return candidate
+        except GitError:
+            continue
+
+    raise RuntimeError(
+        f"Neither {preferred!r} nor {fallback!r} exist in this repository."
+    )

src/pkgmgr/actions/release/README.md

@@ -0,0 +1,218 @@
+# Release Action
+
+This module implements the `pkgmgr release` workflow.
+
+It provides a controlled, reproducible release process that:
+- bumps the project version
+- updates all supported packaging formats
+- creates and pushes Git tags
+- optionally maintains a floating `latest` tag
+- optionally closes the current branch
+
+The implementation is intentionally explicit and conservative to avoid
+accidental releases or broken Git states.
+
+---
+
+## What the Release Command Does
+
+A release performs the following high-level steps:
+
+1. Synchronize the current branch with its upstream (fast-forward only)
+2. Determine the next semantic version
+3. Update all versioned files
+4. Commit the release
+5. Create and push a version tag
+6. Optionally update and push the floating `latest` tag
+7. Optionally close the current branch
+
+All steps support **preview (dry-run)** mode.
+
+---
+
+## Supported Files Updated During a Release
+
+If present, the following files are updated automatically:
+
+- `pyproject.toml`
+- `CHANGELOG.md`
+- `flake.nix`
+- `PKGBUILD`
+- `package-manager.spec`
+- `debian/changelog`
+
+Missing files are skipped gracefully.
+
+---
+
+## Git Safety Rules
+
+The release workflow enforces strict Git safety guarantees:
+
+- A `git pull --ff-only` is executed **before any file modifications**
+- No merge commits are ever created automatically
+- Only the current branch and the newly created version tag are pushed
+- `git push --tags` is intentionally **not** used
+- The floating `latest` tag is force-pushed only when required
+
+---
+
+## Semantic Versioning
+
+The next version is calculated from existing Git tags:
+
+- Tags must follow the format `vX.Y.Z`
+- The release type controls the version bump:
+  - `patch`
+  - `minor`
+  - `major`
+
+The new tag is always created as an **annotated tag**.
+
+---
+
+## Floating `latest` Tag
+
+The floating `latest` tag is handled explicitly:
+
+- `latest` is updated **only if** the new version is the highest existing version
+- Version comparison uses natural version sorting (`sort -V`)
+- `latest` always points to the commit behind the version tag
+- Updating `latest` uses a forced push by design
+
+This guarantees that `latest` always represents the highest released version,
+never an older release.
+
+---
+
+## Preview Mode
+
+Preview mode (`--preview`) performs a full dry-run:
+
+- No files are modified
+- No Git commands are executed
+- All intended actions are printed
+
+Example preview output includes:
+- version bump
+- file updates
+- commit message
+- tag creation
+- branch and tag pushes
+- `latest` update (if applicable)
+
+---
+
+## Interactive vs Forced Mode
+
+### Interactive (default)
+
+1. Run a preview
+2. Ask for confirmation
+3. Execute the real release
+
+### Forced (`--force`)
+
+- Skips preview and confirmation
+- Skips branch deletion prompts
+- Executes the release immediately
+
+---
+
+## Branch Closing (`--close`)
+
+When `--close` is enabled:
+
+- `main` and `master` are **never** deleted
+- Other branches:
+  - prompt for confirmation (`y/N`)
+  - can be skipped using `--force`
+- Branch deletion happens **only after** a successful release
+
+---
+
+## Execution Flow (ASCII Diagram)
+
+```
+
++---------------------+
+| pkgmgr release      |
++----------+----------+
+|
+v
++---------------------+
+| Detect branch       |
++----------+----------+
+|
+v
++------------------------------+
+| git fetch / pull --ff-only   |
++----------+-------------------+
+|
+v
++------------------------------+
+| Determine next version       |
++----------+-------------------+
+|
+v
++------------------------------+
+| Update versioned files       |
++----------+-------------------+
+|
+v
++------------------------------+
+| Commit release               |
++----------+-------------------+
+|
+v
++------------------------------+
+| Create version tag (vX.Y.Z)  |
++----------+-------------------+
+|
+v
++------------------------------+
+| Push branch + version tag    |
++----------+-------------------+
+|
+v
++---------------------------------------+
+| Is this the highest version?           |
++----------+----------------------------+
+|
+yes  |  no
+|
+v
++------------------------------+        +----------------------+
+| Update & push `latest` tag   |        | Skip `latest` update |
++----------+-------------------+        +----------------------+
+|
+v
++------------------------------+
+| Close branch (optional)      |
++------------------------------+
+
+```
+
+---
+
+## Design Goals
+
+- Deterministic and reproducible releases
+- No implicit Git side effects
+- Explicit tag handling
+- Safe defaults for interactive usage
+- Automation-friendly forced mode
+- Clear separation of concerns:
+  - `workflow.py` – orchestration
+  - `git_ops.py` – Git operations
+  - `prompts.py` – user interaction
+  - `versioning.py` – SemVer logic
+
+---
+
+## Summary
+
+`pkgmgr release` is a **deliberately strict** release mechanism.
+
+It trades convenience for safety, traceability, and correctness — making it
+suitable for both interactive development workflows and fully automated CI/CD

src/pkgmgr/actions/release/__init__.py

@@ -1,310 +1,5 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Release helper for pkgmgr (public entry point).
-
-This package provides the high-level `release()` function used by the
-pkgmgr CLI to perform versioned releases:
-
-  - Determine the next semantic version based on existing Git tags.
-  - Update pyproject.toml with the new version.
-  - Update additional packaging files (flake.nix, PKGBUILD,
-    debian/changelog, RPM spec) where present.
-  - Prepend a basic entry to CHANGELOG.md.
-  - Move the floating 'latest' tag to the newly created release tag so
-    the newest release is always marked as latest.
-
-Additional behaviour:
-  - If `preview=True` (from --preview), no files are written and no
-    Git commands are executed. Instead, a detailed summary of the
-    planned changes and commands is printed.
-  - If `preview=False` and not forced, the release is executed in two
-    phases:
-      1) Preview-only run (dry-run).
-      2) Interactive confirmation, then real release if confirmed.
-    This confirmation can be skipped with the `force=True` flag.
-  - Before creating and pushing tags, main/master is updated from origin
-    when the release is performed on one of these branches.
-  - If `close=True` is used and the current branch is not main/master,
-    the branch will be closed via branch_commands.close_branch() after
-    a successful release.
-"""
-
 from __future__ import annotations
 
-import os
+from .workflow import release
-import sys
-from typing import Optional
-
-from pkgmgr.core.git import get_current_branch, GitError
-from pkgmgr.actions.branch import close_branch
-
-from .versioning import determine_current_version, bump_semver
-from .git_ops import run_git_command, sync_branch_with_remote, update_latest_tag
-from .files import (
-    update_pyproject_version,
-    update_flake_version,
-    update_pkgbuild_version,
-    update_spec_version,
-    update_changelog,
-    update_debian_changelog,
-    update_spec_changelog,
-)
-
-
-# ---------------------------------------------------------------------------
-# Internal implementation (single-phase, preview or real)
-# ---------------------------------------------------------------------------
-
-
-def _release_impl(
-    pyproject_path: str = "pyproject.toml",
-    changelog_path: str = "CHANGELOG.md",
-    release_type: str = "patch",
-    message: Optional[str] = None,
-    preview: bool = False,
-    close: bool = False,
-) -> None:
-    """
-    Internal implementation that performs a single-phase release.
-    """
-    current_ver = determine_current_version()
-    new_ver = bump_semver(current_ver, release_type)
-    new_ver_str = str(new_ver)
-    new_tag = new_ver.to_tag(with_prefix=True)
-
-    mode = "PREVIEW" if preview else "REAL"
-    print(f"Release mode: {mode}")
-    print(f"Current version: {current_ver}")
-    print(f"New version:     {new_ver_str} ({release_type})")
-
-    repo_root = os.path.dirname(os.path.abspath(pyproject_path))
-
-    # Update core project metadata and packaging files
-    update_pyproject_version(pyproject_path, new_ver_str, preview=preview)
-    changelog_message = update_changelog(
-        changelog_path,
-        new_ver_str,
-        message=message,
-        preview=preview,
-    )
-
-    flake_path = os.path.join(repo_root, "flake.nix")
-    update_flake_version(flake_path, new_ver_str, preview=preview)
-
-    pkgbuild_path = os.path.join(repo_root, "PKGBUILD")
-    update_pkgbuild_version(pkgbuild_path, new_ver_str, preview=preview)
-
-    spec_path = os.path.join(repo_root, "package-manager.spec")
-    update_spec_version(spec_path, new_ver_str, preview=preview)
-
-    # Determine a single effective_message to be reused across all
-    # changelog targets (project, Debian, Fedora).
-    effective_message: Optional[str] = message
-    if effective_message is None and isinstance(changelog_message, str):
-        if changelog_message.strip():
-            effective_message = changelog_message.strip()
-
-    debian_changelog_path = os.path.join(repo_root, "debian", "changelog")
-    package_name = os.path.basename(repo_root) or "package-manager"
-
-    # Debian changelog
-    update_debian_changelog(
-        debian_changelog_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
-
-    # Fedora / RPM %changelog
-    update_spec_changelog(
-        spec_path=spec_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
-
-    commit_msg = f"Release version {new_ver_str}"
-    tag_msg = effective_message or commit_msg
-
-    # Determine branch and ensure it is up to date if main/master
-    try:
-        branch = get_current_branch() or "main"
-    except GitError:
-        branch = "main"
-    print(f"Releasing on branch: {branch}")
-
-    # Ensure main/master are up-to-date from origin before creating and
-    # pushing tags. For other branches we only log the intent.
-    sync_branch_with_remote(branch, preview=preview)
-
-    files_to_add = [
-        pyproject_path,
-        changelog_path,
-        flake_path,
-        pkgbuild_path,
-        spec_path,
-        debian_changelog_path,
-    ]
-    existing_files = [p for p in files_to_add if p and os.path.exists(p)]
-
-    if preview:
-        for path in existing_files:
-            print(f"[PREVIEW] Would run: git add {path}")
-        print(f'[PREVIEW] Would run: git commit -am "{commit_msg}"')
-        print(f'[PREVIEW] Would run: git tag -a {new_tag} -m "{tag_msg}"')
-        print(f"[PREVIEW] Would run: git push origin {branch}")
-        print("[PREVIEW] Would run: git push origin --tags")
-
-        # Also update the floating 'latest' tag to the new highest SemVer.
-        update_latest_tag(new_tag, preview=True)
-
-        if close and branch not in ("main", "master"):
-            print(
-                f"[PREVIEW] Would also close branch {branch} after the release "
-                "(close=True and branch is not main/master)."
-            )
-        elif close:
-            print(
-                f"[PREVIEW] close=True but current branch is {branch}; "
-                "no branch would be closed."
-            )
-
-        print("Preview completed. No changes were made.")
-        return
-
-    for path in existing_files:
-        run_git_command(f"git add {path}")
-
-    run_git_command(f'git commit -am "{commit_msg}"')
-    run_git_command(f'git tag -a {new_tag} -m "{tag_msg}"')
-    run_git_command(f"git push origin {branch}")
-    run_git_command("git push origin --tags")
-
-    # Move 'latest' to the new release tag so the newest SemVer is always
-    # marked as latest. This is best-effort and must not break the release.
-    try:
-        update_latest_tag(new_tag, preview=False)
-    except GitError as exc:  # pragma: no cover
-        print(
-            f"[WARN] Failed to update floating 'latest' tag for {new_tag}: {exc}\n"
-            "[WARN] The release itself completed successfully; only the "
-            "'latest' tag was not updated."
-        )
-
-    print(f"Release {new_ver_str} completed.")
-
-    if close:
-        if branch in ("main", "master"):
-            print(
-                f"[INFO] close=True but current branch is {branch}; "
-                "nothing to close."
-            )
-            return
-
-        print(
-            f"[INFO] Closing branch {branch} after successful release "
-            "(close=True and branch is not main/master)..."
-        )
-        try:
-            close_branch(name=branch, base_branch="main", cwd=".")
-        except Exception as exc:  # pragma: no cover
-            print(f"[WARN] Failed to close branch {branch} automatically: {exc}")
-
-
-# ---------------------------------------------------------------------------
-# Public release entry point
-# ---------------------------------------------------------------------------
-
-
-def release(
-    pyproject_path: str = "pyproject.toml",
-    changelog_path: str = "CHANGELOG.md",
-    release_type: str = "patch",
-    message: Optional[str] = None,
-    preview: bool = False,
-    force: bool = False,
-    close: bool = False,
-) -> None:
-    """
-    High-level release entry point.
-
-    Modes:
-
-    - preview=True:
-        * Single-phase PREVIEW only.
-
-    - preview=False, force=True:
-        * Single-phase REAL release, no interactive preview.
-
-    - preview=False, force=False:
-        * Two-phase flow (intended default for interactive CLI use).
-    """
-    if preview:
-        _release_impl(
-            pyproject_path=pyproject_path,
-            changelog_path=changelog_path,
-            release_type=release_type,
-            message=message,
-            preview=True,
-            close=close,
-        )
-        return
-
-    if force:
-        _release_impl(
-            pyproject_path=pyproject_path,
-            changelog_path=changelog_path,
-            release_type=release_type,
-            message=message,
-            preview=False,
-            close=close,
-        )
-        return
-
-    if not sys.stdin.isatty():
-        _release_impl(
-            pyproject_path=pyproject_path,
-            changelog_path=changelog_path,
-            release_type=release_type,
-            message=message,
-            preview=False,
-            close=close,
-        )
-        return
-
-    print("[INFO] Running preview before actual release...\n")
-    _release_impl(
-        pyproject_path=pyproject_path,
-        changelog_path=changelog_path,
-        release_type=release_type,
-        message=message,
-        preview=True,
-        close=close,
-    )
-
-    try:
-        answer = input("Proceed with the actual release? [y/N]: ").strip().lower()
-    except (EOFError, KeyboardInterrupt):
-        print("\n[INFO] Release aborted (no confirmation).")
-        return
-
-    if answer not in ("y", "yes"):
-        print("Release aborted by user. No changes were made.")
-        return
-
-    print("\n[INFO] Running REAL release...\n")
-    _release_impl(
-        pyproject_path=pyproject_path,
-        changelog_path=changelog_path,
-        release_type=release_type,
-        message=message,
-        preview=False,
-        close=close,
-    )
-
 
 __all__ = ["release"]

src/pkgmgr/actions/release/git_ops.py

@@ -1,16 +1,3 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Git-related helpers for the release workflow.
-
-Responsibilities:
-  - Run Git (or shell) commands with basic error reporting.
-  - Ensure main/master are synchronized with origin before tagging.
-  - Maintain the floating 'latest' tag that always points to the newest
-    release tag.
-"""
-
 from __future__ import annotations
 
 import subprocess
@@ -19,77 +6,87 @@ from pkgmgr.core.git import GitError
 
 
 def run_git_command(cmd: str) -> None:
-    """
-    Run a Git (or shell) command with basic error reporting.
-
-    The command is executed via the shell, primarily for readability
-    when printed (as in 'git commit -am "msg"').
-    """
     print(f"[GIT] {cmd}")
     try:
-        subprocess.run(cmd, shell=True, check=True)
+        subprocess.run(
+            cmd,
+            shell=True,
+            check=True,
+            text=True,
+            capture_output=True,
+        )
     except subprocess.CalledProcessError as exc:
         print(f"[ERROR] Git command failed: {cmd}")
         print(f"        Exit code: {exc.returncode}")
         if exc.stdout:
-            print("--- stdout ---")
+            print("\n" + exc.stdout)
-            print(exc.stdout)
         if exc.stderr:
-            print("--- stderr ---")
+            print("\n" + exc.stderr)
-            print(exc.stderr)
         raise GitError(f"Git command failed: {cmd}") from exc
 
 
-def sync_branch_with_remote(branch: str, preview: bool = False) -> None:
+def _capture(cmd: str) -> str:
-    """
+    res = subprocess.run(cmd, shell=True, check=False, capture_output=True, text=True)
-    Ensure the local main/master branch is up-to-date before tagging.
+    return (res.stdout or "").strip()
 
-    Behaviour:
+
-      - For main/master: run 'git fetch origin' and 'git pull origin <branch>'.
+def ensure_clean_and_synced(preview: bool = False) -> None:
-      - For all other branches: only log that no automatic sync is performed.
     """
-    if branch not in ("main", "master"):
+    Always run a pull BEFORE modifying anything.
-        print(
+    Uses --ff-only to avoid creating merge commits automatically.
-            f"[INFO] Skipping automatic git pull for non-main/master branch "
+    If no upstream is configured, we skip.
-            f"{branch}."
+    """
-        )
+    upstream = _capture("git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null")
+    if not upstream:
+        print("[INFO] No upstream configured for current branch. Skipping pull.")
         return
 
-    print(
-        f"[INFO] Updating branch {branch} from origin before creating tags..."
-    )
-
     if preview:
-        print("[PREVIEW] Would run: git fetch origin")
+        print("[PREVIEW] Would run: git fetch origin --prune --tags --force")
-        print(f"[PREVIEW] Would run: git pull origin {branch}")
+        print("[PREVIEW] Would run: git pull --ff-only")
         return
 
-    run_git_command("git fetch origin")
+    print("[INFO] Syncing with remote before making any changes...")
-    run_git_command(f"git pull origin {branch}")
+    run_git_command("git fetch origin --prune --tags --force")
+    run_git_command("git pull --ff-only")
+
+def is_highest_version_tag(tag: str) -> bool:
+    """
+    Return True if `tag` is the highest version among all tags matching v*.
+    Comparison uses `sort -V` for natural version ordering.
+    """
+    all_v = _capture("git tag --list 'v*'")
+    if not all_v:
+        return True  # No tags yet, so the current tag is the highest
+
+    # Get the latest tag in natural version order
+    latest = _capture("git tag --list 'v*' | sort -V | tail -n1")
+    print(f"[INFO] Latest tag: {latest}, Current tag: {tag}")
+    
+    # Ensure that the current tag is always considered the highest if it's the latest one
+    return tag >= latest  # Use comparison operator to consider all future tags
 
 
 def update_latest_tag(new_tag: str, preview: bool = False) -> None:
     """
     Move the floating 'latest' tag to the newly created release tag.
 
-    Implementation details:
+    Notes:
-      - We explicitly dereference the tag object via `<tag>^{}` so that
+    - We dereference the tag object via `<tag>^{}` so that 'latest' points to the commit.
-        'latest' always points at the underlying commit, not at another tag.
+    - 'latest' is forced (floating tag), therefore the push uses --force.
-      - We create/update 'latest' as an annotated tag with a short message so
-        Git configurations that enforce annotated/signed tags do not fail
-        with "no tag message".
     """
     target_ref = f"{new_tag}^{{}}"
     print(f"[INFO] Updating 'latest' tag to point at {new_tag} (commit {target_ref})...")
 
     if preview:
-        print(f"[PREVIEW] Would run: git tag -f -a latest {target_ref} "
+        print(
-              f'-m "Floating latest tag for {new_tag}"')
+            f'[PREVIEW] Would run: git tag -f -a latest {target_ref} '
+            f'-m "Floating latest tag for {new_tag}"'
+        )
         print("[PREVIEW] Would run: git push origin latest --force")
         return
 
     run_git_command(
-        f'git tag -f -a latest {target_ref} '
+        f'git tag -f -a latest {target_ref} -m "Floating latest tag for {new_tag}"'
-        f'-m "Floating latest tag for {new_tag}"'
     )
     run_git_command("git push origin latest --force")

src/pkgmgr/actions/release/prompts.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import sys
+
+
+def should_delete_branch(force: bool) -> bool:
+    """
+    Ask whether the current branch should be deleted after a successful release.
+
+    - If force=True: skip prompt and return True.
+    - If non-interactive stdin: do NOT delete by default.
+    """
+    if force:
+        return True
+    if not sys.stdin.isatty():
+        return False
+    answer = input("Delete the current branch after release? [y/N] ").strip().lower()
+    return answer in ("y", "yes")
+
+
+def confirm_proceed_release() -> bool:
+    """
+    Ask whether to proceed with the REAL release after the preview phase.
+    """
+    try:
+        answer = input("Proceed with the actual release? [y/N]: ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return False
+    return answer in ("y", "yes")

src/pkgmgr/actions/release/workflow.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+from pkgmgr.actions.branch import close_branch
+from pkgmgr.core.git import get_current_branch, GitError
+
+from .files import (
+    update_changelog,
+    update_debian_changelog,
+    update_flake_version,
+    update_pkgbuild_version,
+    update_pyproject_version,
+    update_spec_changelog,
+    update_spec_version,
+)
+from .git_ops import (
+    ensure_clean_and_synced,
+    is_highest_version_tag,
+    run_git_command,
+    update_latest_tag,
+)
+from .prompts import confirm_proceed_release, should_delete_branch
+from .versioning import bump_semver, determine_current_version
+
+
+def _release_impl(
+    pyproject_path: str = "pyproject.toml",
+    changelog_path: str = "CHANGELOG.md",
+    release_type: str = "patch",
+    message: Optional[str] = None,
+    preview: bool = False,
+    close: bool = False,
+    force: bool = False,
+) -> None:
+    # Determine current branch early
+    try:
+        branch = get_current_branch() or "main"
+    except GitError:
+        branch = "main"
+    print(f"Releasing on branch: {branch}")
+
+    # Pull BEFORE making any modifications
+    ensure_clean_and_synced(preview=preview)
+
+    current_ver = determine_current_version()
+    new_ver = bump_semver(current_ver, release_type)
+    new_ver_str = str(new_ver)
+    new_tag = new_ver.to_tag(with_prefix=True)
+
+    mode = "PREVIEW" if preview else "REAL"
+    print(f"Release mode: {mode}")
+    print(f"Current version: {current_ver}")
+    print(f"New version:     {new_ver_str} ({release_type})")
+
+    repo_root = os.path.dirname(os.path.abspath(pyproject_path))
+
+    update_pyproject_version(pyproject_path, new_ver_str, preview=preview)
+    changelog_message = update_changelog(
+        changelog_path,
+        new_ver_str,
+        message=message,
+        preview=preview,
+    )
+
+    flake_path = os.path.join(repo_root, "flake.nix")
+    update_flake_version(flake_path, new_ver_str, preview=preview)
+
+    pkgbuild_path = os.path.join(repo_root, "PKGBUILD")
+    update_pkgbuild_version(pkgbuild_path, new_ver_str, preview=preview)
+
+    spec_path = os.path.join(repo_root, "package-manager.spec")
+    update_spec_version(spec_path, new_ver_str, preview=preview)
+
+    effective_message: Optional[str] = message
+    if effective_message is None and isinstance(changelog_message, str):
+        if changelog_message.strip():
+            effective_message = changelog_message.strip()
+
+    debian_changelog_path = os.path.join(repo_root, "debian", "changelog")
+    package_name = os.path.basename(repo_root) or "package-manager"
+
+    update_debian_changelog(
+        debian_changelog_path,
+        package_name=package_name,
+        new_version=new_ver_str,
+        message=effective_message,
+        preview=preview,
+    )
+
+    update_spec_changelog(
+        spec_path=spec_path,
+        package_name=package_name,
+        new_version=new_ver_str,
+        message=effective_message,
+        preview=preview,
+    )
+
+    commit_msg = f"Release version {new_ver_str}"
+    tag_msg = effective_message or commit_msg
+
+    files_to_add = [
+        pyproject_path,
+        changelog_path,
+        flake_path,
+        pkgbuild_path,
+        spec_path,
+        debian_changelog_path,
+    ]
+    existing_files = [p for p in files_to_add if p and os.path.exists(p)]
+
+    if preview:
+        for path in existing_files:
+            print(f"[PREVIEW] Would run: git add {path}")
+        print(f'[PREVIEW] Would run: git commit -am "{commit_msg}"')
+        print(f'[PREVIEW] Would run: git tag -a {new_tag} -m "{tag_msg}"')
+        print(f"[PREVIEW] Would run: git push origin {branch}")
+        print(f"[PREVIEW] Would run: git push origin {new_tag}")
+
+        if is_highest_version_tag(new_tag):
+            update_latest_tag(new_tag, preview=True)
+        else:
+            print(f"[PREVIEW] Skipping 'latest' update (tag {new_tag} is not the highest).")
+
+        if close and branch not in ("main", "master"):
+            if force:
+                print(f"[PREVIEW] Would delete branch {branch} (forced).")
+            else:
+                print(f"[PREVIEW] Would ask whether to delete branch {branch} after release.")
+        return
+
+    for path in existing_files:
+        run_git_command(f"git add {path}")
+
+    run_git_command(f'git commit -am "{commit_msg}"')
+    run_git_command(f'git tag -a {new_tag} -m "{tag_msg}"')
+
+    # Push branch and ONLY the newly created version tag (no --tags)
+    run_git_command(f"git push origin {branch}")
+    run_git_command(f"git push origin {new_tag}")
+
+    # Update 'latest' only if this is the highest version tag
+    try:
+        if is_highest_version_tag(new_tag):
+            update_latest_tag(new_tag, preview=False)
+        else:
+            print(f"[INFO] Skipping 'latest' update (tag {new_tag} is not the highest).")
+    except GitError as exc:
+        print(f"[WARN] Failed to update floating 'latest' tag for {new_tag}: {exc}")
+        print("'latest' tag was not updated.")
+
+    print(f"Release {new_ver_str} completed.")
+
+    if close:
+        if branch in ("main", "master"):
+            print(f"[INFO] close=True but current branch is {branch}; skipping branch deletion.")
+            return
+
+        if not should_delete_branch(force=force):
+            print(f"[INFO] Branch deletion declined. Keeping branch {branch}.")
+            return
+
+        print(f"[INFO] Deleting branch {branch} after successful release...")
+        try:
+            close_branch(name=branch, base_branch="main", cwd=".")
+        except Exception as exc:
+            print(f"[WARN] Failed to close branch {branch} automatically: {exc}")
+
+
+def release(
+    pyproject_path: str = "pyproject.toml",
+    changelog_path: str = "CHANGELOG.md",
+    release_type: str = "patch",
+    message: Optional[str] = None,
+    preview: bool = False,
+    force: bool = False,
+    close: bool = False,
+) -> None:
+    if preview:
+        _release_impl(
+            pyproject_path=pyproject_path,
+            changelog_path=changelog_path,
+            release_type=release_type,
+            message=message,
+            preview=True,
+            close=close,
+            force=force,
+        )
+        return
+
+    # If force or non-interactive: no preview+confirmation step
+    if force or (not sys.stdin.isatty()):
+        _release_impl(
+            pyproject_path=pyproject_path,
+            changelog_path=changelog_path,
+            release_type=release_type,
+            message=message,
+            preview=False,
+            close=close,
+            force=force,
+        )
+        return
+
+    print("[INFO] Running preview before actual release...\n")
+    _release_impl(
+        pyproject_path=pyproject_path,
+        changelog_path=changelog_path,
+        release_type=release_type,
+        message=message,
+        preview=True,
+        close=close,
+        force=force,
+    )
+
+    if not confirm_proceed_release():
+        print()
+        return
+
+    print("\n[INFO] Running REAL release...\n")
+    _release_impl(
+        pyproject_path=pyproject_path,
+        changelog_path=changelog_path,
+        release_type=release_type,
+        message=message,
+        preview=False,
+        close=close,
+        force=force,
+    )

src/pkgmgr/cli/commands/branch.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import sys
 
 from pkgmgr.cli.context import CLIContext
-from pkgmgr.actions.branch import open_branch, close_branch
+from pkgmgr.actions.branch import open_branch, close_branch, drop_branch
 
 
 def handle_branch(args, ctx: CLIContext) -> None:
@@ -12,7 +12,8 @@ def handle_branch(args, ctx: CLIContext) -> None:
 
     Currently supported:
       - pkgmgr branch open  [<name>] [--base <branch>]
-      - pkgmgr branch close [<name>] [--base <branch>]
+      - pkgmgr branch close [<name>] [--base <branch>] [--force|-f]
+      - pkgmgr branch drop  [<name>] [--base <branch>] [--force|-f]
     """
     if args.subcommand == "open":
         open_branch(
@@ -27,6 +28,16 @@ def handle_branch(args, ctx: CLIContext) -> None:
             name=getattr(args, "name", None),
             base_branch=getattr(args, "base", "main"),
             cwd=".",
+            force=getattr(args, "force", False),
+        )
+        return
+
+    if args.subcommand == "drop":
+        drop_branch(
+            name=getattr(args, "name", None),
+            base_branch=getattr(args, "base", "main"),
+            cwd=".",
+            force=getattr(args, "force", False),
         )
         return
 

src/pkgmgr/cli/parser/branch_cmd.py

@@ -14,7 +14,7 @@ def add_branch_subparsers(
     """
     branch_parser = subparsers.add_parser(
         "branch",
-        help="Branch-related utilities (e.g. open/close feature branches)",
+        help="Branch-related utilities (e.g. open/close/drop feature branches)",
     )
     branch_subparsers = branch_parser.add_subparsers(
         dest="subcommand",
@@ -22,6 +22,9 @@ def add_branch_subparsers(
         required=True,
     )
 
+    # -----------------------------------------------------------------------
+    # branch open
+    # -----------------------------------------------------------------------
     branch_open = branch_subparsers.add_parser(
         "open",
         help="Create and push a new branch on top of a base branch",
@@ -40,6 +43,9 @@ def add_branch_subparsers(
         help="Base branch to create the new branch from (default: main)",
     )
 
+    # -----------------------------------------------------------------------
+    # branch close
+    # -----------------------------------------------------------------------
     branch_close = branch_subparsers.add_parser(
         "close",
         help="Merge a feature branch into base and delete it",
@@ -60,3 +66,39 @@ def add_branch_subparsers(
             "internally if main does not exist)"
         ),
     )
+    branch_close.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Skip confirmation prompt and close the branch directly",
+    )
+
+    # -----------------------------------------------------------------------
+    # branch drop
+    # -----------------------------------------------------------------------
+    branch_drop = branch_subparsers.add_parser(
+        "drop",
+        help="Delete a branch locally and on origin (without merging)",
+    )
+    branch_drop.add_argument(
+        "name",
+        nargs="?",
+        help=(
+            "Name of the branch to drop (optional; current branch is used "
+            "if omitted)"
+        ),
+    )
+    branch_drop.add_argument(
+        "--base",
+        default="main",
+        help=(
+            "Base branch used to protect main/master from deletion "
+            "(default: main; falls back to master internally)"
+        ),
+    )
+    branch_drop.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="Skip confirmation prompt and drop the branch directly",
+    )

tests/e2e/test_branch_help.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import io
+import runpy
+import sys
+import unittest
+from contextlib import redirect_stdout, redirect_stderr
+
+
+def _run_pkgmgr_help(argv_tail: list[str]) -> str:
+    """
+    Run `pkgmgr <argv_tail> --help` via the main module and return captured output.
+
+    argparse parses sys.argv[1:], so argv[0] must be a dummy program name.
+    Any SystemExit with code 0 or None is treated as success.
+    """
+    original_argv = list(sys.argv)
+    buffer = io.StringIO()
+    cmd_repr = "pkgmgr " + " ".join(argv_tail) + " --help"
+
+    try:
+        # IMPORTANT: argv[0] must be a dummy program name
+        sys.argv = ["pkgmgr"] + list(argv_tail) + ["--help"]
+
+        try:
+            with redirect_stdout(buffer), redirect_stderr(buffer):
+                runpy.run_module("main", run_name="__main__")
+        except SystemExit as exc:
+            code = exc.code if isinstance(exc.code, int) else None
+            if code not in (0, None):
+                raise AssertionError(
+                    f"{cmd_repr!r} failed with exit code {exc.code}."
+                ) from exc
+
+        return buffer.getvalue()
+    finally:
+        sys.argv = original_argv
+
+
+class TestBranchHelpE2E(unittest.TestCase):
+    """
+    End-to-end tests ensuring that `pkgmgr branch` help commands
+    run without error and print usage information.
+    """
+
+    def test_branch_root_help(self) -> None:
+        """
+        `pkgmgr branch --help` should run without error.
+        """
+        output = _run_pkgmgr_help(["branch"])
+        self.assertIn("usage:", output)
+        self.assertIn("pkgmgr branch", output)
+
+    def test_branch_open_help(self) -> None:
+        """
+        `pkgmgr branch open --help` should run without error.
+        """
+        output = _run_pkgmgr_help(["branch", "open"])
+        self.assertIn("usage:", output)
+        self.assertIn("branch open", output)
+
+    def test_branch_close_help(self) -> None:
+        """
+        `pkgmgr branch close --help` should run without error.
+        """
+        output = _run_pkgmgr_help(["branch", "close"])
+        self.assertIn("usage:", output)
+        self.assertIn("branch close", output)
+
+    def test_branch_drop_help(self) -> None:
+        """
+        `pkgmgr branch drop --help` should run without error.
+        """
+        output = _run_pkgmgr_help(["branch", "drop"])
+        self.assertIn("usage:", output)
+        self.assertIn("branch drop", output)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_branch_cli.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Integration tests for the `pkgmgr branch` CLI wiring.
+
+These tests verify that:
+  - The argument parser creates the correct structure for
+    `branch open`, `branch close` and `branch drop`.
+  - `handle_branch` calls the corresponding helper functions
+    with the expected arguments (including base branch, cwd and force).
+"""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.cli.parser import create_parser
+from pkgmgr.cli.commands.branch import handle_branch
+
+
+class TestBranchCLI(unittest.TestCase):
+    """
+    Tests for the branch subcommands implemented in the CLI.
+    """
+
+    def _create_parser(self):
+        """
+        Create the top-level parser with a minimal description.
+        """
+        return create_parser("pkgmgr test parser")
+
+    # --------------------------------------------------------------------- #
+    # branch open
+    # --------------------------------------------------------------------- #
+
+    @patch("pkgmgr.cli.commands.branch.open_branch")
+    def test_branch_open_with_name_and_base(self, mock_open_branch):
+        """
+        Ensure that `pkgmgr branch open <name> --base <branch>` calls
+        open_branch() with the correct parameters.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(
+            ["branch", "open", "feature/test-branch", "--base", "develop"]
+        )
+
+        # Sanity check: parser wiring
+        self.assertEqual(args.command, "branch")
+        self.assertEqual(args.subcommand, "open")
+        self.assertEqual(args.name, "feature/test-branch")
+        self.assertEqual(args.base, "develop")
+
+        # ctx is currently unused by handle_branch, so we can pass None
+        handle_branch(args, ctx=None)
+
+        mock_open_branch.assert_called_once()
+        _args, kwargs = mock_open_branch.call_args
+
+        self.assertEqual(kwargs.get("name"), "feature/test-branch")
+        self.assertEqual(kwargs.get("base_branch"), "develop")
+        self.assertEqual(kwargs.get("cwd"), ".")
+
+    @patch("pkgmgr.cli.commands.branch.open_branch")
+    def test_branch_open_with_name_and_default_base(self, mock_open_branch):
+        """
+        Ensure that `pkgmgr branch open <name>` without --base uses
+        the default base branch 'main'.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(["branch", "open", "feature/default-base"])
+
+        self.assertEqual(args.command, "branch")
+        self.assertEqual(args.subcommand, "open")
+        self.assertEqual(args.name, "feature/default-base")
+        self.assertEqual(args.base, "main")
+
+        handle_branch(args, ctx=None)
+
+        mock_open_branch.assert_called_once()
+        _args, kwargs = mock_open_branch.call_args
+
+        self.assertEqual(kwargs.get("name"), "feature/default-base")
+        self.assertEqual(kwargs.get("base_branch"), "main")
+        self.assertEqual(kwargs.get("cwd"), ".")
+
+    # --------------------------------------------------------------------- #
+    # branch close
+    # --------------------------------------------------------------------- #
+
+    @patch("pkgmgr.cli.commands.branch.close_branch")
+    def test_branch_close_with_name_and_base(self, mock_close_branch):
+        """
+        Ensure that `pkgmgr branch close <name> --base <branch>` calls
+        close_branch() with the correct parameters and force=False by default.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(
+            ["branch", "close", "feature/old-branch", "--base", "main"]
+        )
+
+        # Sanity check: parser wiring
+        self.assertEqual(args.command, "branch")
+        self.assertEqual(args.subcommand, "close")
+        self.assertEqual(args.name, "feature/old-branch")
+        self.assertEqual(args.base, "main")
+        self.assertFalse(args.force)
+
+        handle_branch(args, ctx=None)
+
+        mock_close_branch.assert_called_once()
+        _args, kwargs = mock_close_branch.call_args
+
+        self.assertEqual(kwargs.get("name"), "feature/old-branch")
+        self.assertEqual(kwargs.get("base_branch"), "main")
+        self.assertEqual(kwargs.get("cwd"), ".")
+        self.assertFalse(kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.close_branch")
+    def test_branch_close_without_name_uses_none(self, mock_close_branch):
+        """
+        Ensure that `pkgmgr branch close` without a name passes name=None
+        into close_branch(), leaving branch resolution to the helper.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(["branch", "close"])
+
+        # Parser wiring: no name → None
+        self.assertEqual(args.command, "branch")
+        self.assertEqual(args.subcommand, "close")
+        self.assertIsNone(args.name)
+        self.assertEqual(args.base, "main")
+        self.assertFalse(args.force)
+
+        handle_branch(args, ctx=None)
+
+        mock_close_branch.assert_called_once()
+        _args, kwargs = mock_close_branch.call_args
+
+        self.assertIsNone(kwargs.get("name"))
+        self.assertEqual(kwargs.get("base_branch"), "main")
+        self.assertEqual(kwargs.get("cwd"), ".")
+        self.assertFalse(kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.close_branch")
+    def test_branch_close_with_force(self, mock_close_branch):
+        """
+        Ensure that `pkgmgr branch close <name> --force` passes force=True.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(
+            ["branch", "close", "feature/old-branch", "--base", "main", "--force"]
+        )
+
+        self.assertTrue(args.force)
+
+        handle_branch(args, ctx=None)
+
+        mock_close_branch.assert_called_once()
+        _args, kwargs = mock_close_branch.call_args
+
+        self.assertEqual(kwargs.get("name"), "feature/old-branch")
+        self.assertEqual(kwargs.get("base_branch"), "main")
+        self.assertEqual(kwargs.get("cwd"), ".")
+        self.assertTrue(kwargs.get("force"))
+
+    # --------------------------------------------------------------------- #
+    # branch drop
+    # --------------------------------------------------------------------- #
+
+    @patch("pkgmgr.cli.commands.branch.drop_branch")
+    def test_branch_drop_with_name_and_base(self, mock_drop_branch):
+        """
+        Ensure that `pkgmgr branch drop <name> --base <branch>` calls
+        drop_branch() with the correct parameters and force=False by default.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(
+            ["branch", "drop", "feature/tmp-branch", "--base", "develop"]
+        )
+
+        self.assertEqual(args.command, "branch")
+        self.assertEqual(args.subcommand, "drop")
+        self.assertEqual(args.name, "feature/tmp-branch")
+        self.assertEqual(args.base, "develop")
+        self.assertFalse(args.force)
+
+        handle_branch(args, ctx=None)
+
+        mock_drop_branch.assert_called_once()
+        _args, kwargs = mock_drop_branch.call_args
+
+        self.assertEqual(kwargs.get("name"), "feature/tmp-branch")
+        self.assertEqual(kwargs.get("base_branch"), "develop")
+        self.assertEqual(kwargs.get("cwd"), ".")
+        self.assertFalse(kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.drop_branch")
+    def test_branch_drop_without_name(self, mock_drop_branch):
+        """
+        Ensure that `pkgmgr branch drop` without a name passes name=None
+        into drop_branch(), leaving branch resolution to the helper.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(["branch", "drop"])
+
+        self.assertEqual(args.command, "branch")
+        self.assertEqual(args.subcommand, "drop")
+        self.assertIsNone(args.name)
+        self.assertEqual(args.base, "main")
+        self.assertFalse(args.force)
+
+        handle_branch(args, ctx=None)
+
+        mock_drop_branch.assert_called_once()
+        _args, kwargs = mock_drop_branch.call_args
+
+        self.assertIsNone(kwargs.get("name"))
+        self.assertEqual(kwargs.get("base_branch"), "main")
+        self.assertEqual(kwargs.get("cwd"), ".")
+        self.assertFalse(kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.drop_branch")
+    def test_branch_drop_with_force(self, mock_drop_branch):
+        """
+        Ensure that `pkgmgr branch drop <name> --force` passes force=True.
+        """
+        parser = self._create_parser()
+        args = parser.parse_args(
+            ["branch", "drop", "feature/tmp-branch", "--force"]
+        )
+
+        self.assertTrue(args.force)
+
+        handle_branch(args, ctx=None)
+
+        mock_drop_branch.assert_called_once()
+        _args, kwargs = mock_drop_branch.call_args
+
+        self.assertEqual(kwargs.get("name"), "feature/tmp-branch")
+        self.assertEqual(kwargs.get("base_branch"), "main")
+        self.assertEqual(kwargs.get("cwd"), ".")
+        self.assertTrue(kwargs.get("force"))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/branch/__init__.py

@@ -0,0 +1,33 @@
+import unittest
+from unittest.mock import patch, MagicMock
+
+from pkgmgr.actions.branch.utils import _resolve_base_branch
+from pkgmgr.core.git import GitError
+
+
+class TestResolveBaseBranch(unittest.TestCase):
+    @patch("pkgmgr.actions.branch.utils.run_git")
+    def test_resolves_preferred(self, run_git):
+        run_git.return_value = None
+        result = _resolve_base_branch("main", "master", cwd=".")
+        self.assertEqual(result, "main")
+        run_git.assert_called_with(["rev-parse", "--verify", "main"], cwd=".")
+
+    @patch("pkgmgr.actions.branch.utils.run_git")
+    def test_resolves_fallback(self, run_git):
+        run_git.side_effect = [
+            GitError("main missing"),
+            None,
+        ]
+        result = _resolve_base_branch("main", "master", cwd=".")
+        self.assertEqual(result, "master")
+
+    @patch("pkgmgr.actions.branch.utils.run_git")
+    def test_raises_when_no_branch_exists(self, run_git):
+        run_git.side_effect = GitError("missing")
+        with self.assertRaises(RuntimeError):
+            _resolve_base_branch("main", "master", cwd=".")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/branch/test_close_branch.py

@@ -0,0 +1,55 @@
+import unittest
+from unittest.mock import patch, MagicMock
+
+from pkgmgr.actions.branch.close_branch import close_branch
+from pkgmgr.core.git import GitError
+
+
+class TestCloseBranch(unittest.TestCase):
+    @patch("pkgmgr.actions.branch.close_branch.input", return_value="y")
+    @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.run_git")
+    def test_close_branch_happy_path(self, run_git, resolve, current, input_mock):
+        close_branch(None, cwd=".")
+        expected = [
+            (["fetch", "origin"],),
+            (["checkout", "main"],),
+            (["pull", "origin", "main"],),
+            (["merge", "--no-ff", "feature-x"],),
+            (["push", "origin", "main"],),
+            (["branch", "-d", "feature-x"],),
+            (["push", "origin", "--delete", "feature-x"],),
+        ]
+        actual = [call.args for call in run_git.call_args_list]
+        self.assertEqual(actual, expected)
+
+    @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
+    def test_refuses_to_close_base_branch(self, resolve, current):
+        with self.assertRaises(RuntimeError):
+            close_branch(None)
+
+    @patch("pkgmgr.actions.branch.close_branch.input", return_value="n")
+    @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.run_git")
+    def test_close_branch_aborts_on_no(self, run_git, resolve, current, input_mock):
+        close_branch(None, cwd=".")
+        run_git.assert_not_called()
+
+    @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.run_git")
+    def test_close_branch_force_skips_prompt(self, run_git, resolve, current):
+        close_branch(None, cwd=".", force=True)
+        self.assertGreater(len(run_git.call_args_list), 0)
+
+    @patch("pkgmgr.actions.branch.close_branch.get_current_branch", side_effect=GitError("fail"))
+    def test_close_branch_errors_if_cannot_detect_branch(self, current):
+        with self.assertRaises(RuntimeError):
+            close_branch(None)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/branch/test_drop_branch.py

@@ -0,0 +1,50 @@
+import unittest
+from unittest.mock import patch, MagicMock
+
+from pkgmgr.actions.branch.drop_branch import drop_branch
+from pkgmgr.core.git import GitError
+
+
+class TestDropBranch(unittest.TestCase):
+    @patch("pkgmgr.actions.branch.drop_branch.input", return_value="y")
+    @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.run_git")
+    def test_drop_branch_happy_path(self, run_git, resolve, current, input_mock):
+        drop_branch(None, cwd=".")
+        expected = [
+            (["branch", "-d", "feature-x"],),
+            (["push", "origin", "--delete", "feature-x"],),
+        ]
+        actual = [call.args for call in run_git.call_args_list]
+        self.assertEqual(actual, expected)
+
+    @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
+    def test_refuses_to_drop_base_branch(self, resolve, current):
+        with self.assertRaises(RuntimeError):
+            drop_branch(None)
+
+    @patch("pkgmgr.actions.branch.drop_branch.input", return_value="n")
+    @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.run_git")
+    def test_drop_branch_aborts_on_no(self, run_git, resolve, current, input_mock):
+        drop_branch(None, cwd=".")
+        run_git.assert_not_called()
+
+    @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.run_git")
+    def test_drop_branch_force_skips_prompt(self, run_git, resolve, current):
+        drop_branch(None, cwd=".", force=True)
+        self.assertGreater(len(run_git.call_args_list), 0)
+
+    @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", side_effect=GitError("fail"))
+    def test_drop_branch_errors_if_no_branch_detected(self, current):
+        with self.assertRaises(RuntimeError):
+            drop_branch(None)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/branch/test_open_branch.py

@@ -0,0 +1,37 @@
+import unittest
+from unittest.mock import patch, MagicMock
+
+from pkgmgr.actions.branch.open_branch import open_branch
+
+
+class TestOpenBranch(unittest.TestCase):
+    @patch("pkgmgr.actions.branch.open_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.open_branch.run_git")
+    def test_open_branch_executes_git_commands(self, run_git, resolve):
+        open_branch("feature-x", base_branch="main", cwd=".")
+        expected_calls = [
+            (["fetch", "origin"],),
+            (["checkout", "main"],),
+            (["pull", "origin", "main"],),
+            (["checkout", "-b", "feature-x"],),
+            (["push", "-u", "origin", "feature-x"],),
+        ]
+        actual = [call.args for call in run_git.call_args_list]
+        self.assertEqual(actual, expected_calls)
+
+    @patch("builtins.input", return_value="auto-branch")
+    @patch("pkgmgr.actions.branch.open_branch._resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.open_branch.run_git")
+    def test_open_branch_prompts_for_name(self, run_git, resolve, input_mock):
+        open_branch(None)
+        calls = [call.args for call in run_git.call_args_list]
+        self.assertEqual(calls[3][0][0], "checkout")  # verify git executed normally
+
+    def test_open_branch_rejects_empty_name(self):
+        with patch("builtins.input", return_value=""):
+            with self.assertRaises(RuntimeError):
+                open_branch(None)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/release/test_git_ops.py

@@ -5,8 +5,9 @@ from unittest.mock import patch
 
 from pkgmgr.core.git import GitError
 from pkgmgr.actions.release.git_ops import (
+    ensure_clean_and_synced,
+    is_highest_version_tag,
     run_git_command,
-    sync_branch_with_remote,
     update_latest_tag,
 )
 
@@ -14,12 +15,13 @@ from pkgmgr.actions.release.git_ops import (
 class TestRunGitCommand(unittest.TestCase):
     @patch("pkgmgr.actions.release.git_ops.subprocess.run")
     def test_run_git_command_success(self, mock_run) -> None:
-        # No exception means success
         run_git_command("git status")
         mock_run.assert_called_once()
         args, kwargs = mock_run.call_args
         self.assertIn("git status", args[0])
         self.assertTrue(kwargs.get("check"))
+        self.assertTrue(kwargs.get("capture_output"))
+        self.assertTrue(kwargs.get("text"))
 
     @patch("pkgmgr.actions.release.git_ops.subprocess.run")
     def test_run_git_command_failure_raises_git_error(self, mock_run) -> None:
@@ -36,58 +38,161 @@ class TestRunGitCommand(unittest.TestCase):
             run_git_command("git status")
 
 
-class TestSyncBranchWithRemote(unittest.TestCase):
+class TestEnsureCleanAndSynced(unittest.TestCase):
-    @patch("pkgmgr.actions.release.git_ops.run_git_command")
+    def _fake_run(self, cmd: str, *args, **kwargs):
-    def test_sync_branch_with_remote_skips_non_main_master(
+        class R:
-        self,
+            def __init__(self, stdout: str = "", stderr: str = "", returncode: int = 0):
-        mock_run_git_command,
+                self.stdout = stdout
-    ) -> None:
+                self.stderr = stderr
-        sync_branch_with_remote("feature/my-branch", preview=False)
+                self.returncode = returncode
-        mock_run_git_command.assert_not_called()
 
-    @patch("pkgmgr.actions.release.git_ops.run_git_command")
+        # upstream detection
-    def test_sync_branch_with_remote_preview_on_main_does_not_run_git(
+        if "git rev-parse --abbrev-ref --symbolic-full-name @{u}" in cmd:
-        self,
+            return R(stdout="origin/main")
-        mock_run_git_command,
-    ) -> None:
-        sync_branch_with_remote("main", preview=True)
-        mock_run_git_command.assert_not_called()
 
-    @patch("pkgmgr.actions.release.git_ops.run_git_command")
+        # fetch/pull should be invoked in real mode
-    def test_sync_branch_with_remote_main_runs_fetch_and_pull(
+        if cmd == "git fetch --prune --tags":
-        self,
+            return R(stdout="")
-        mock_run_git_command,
+        if cmd == "git pull --ff-only":
-    ) -> None:
+            return R(stdout="Already up to date.")
-        sync_branch_with_remote("main", preview=False)
 
-        calls = [c.args[0] for c in mock_run_git_command.call_args_list]
+        return R(stdout="")
-        self.assertIn("git fetch origin", calls)
+
-        self.assertIn("git pull origin main", calls)
+    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
+    def test_ensure_clean_and_synced_preview_does_not_run_git_commands(self, mock_run) -> None:
+        def fake(cmd: str, *args, **kwargs):
+            class R:
+                def __init__(self, stdout: str = ""):
+                    self.stdout = stdout
+                    self.stderr = ""
+                    self.returncode = 0
+
+            if "git rev-parse --abbrev-ref --symbolic-full-name @{u}" in cmd:
+                return R(stdout="origin/main")
+            return R(stdout="")
+
+        mock_run.side_effect = fake
+
+        ensure_clean_and_synced(preview=True)
+
+        called_cmds = [c.args[0] for c in mock_run.call_args_list]
+        self.assertTrue(any("git rev-parse" in c for c in called_cmds))
+        self.assertFalse(any(c == "git fetch --prune --tags" for c in called_cmds))
+        self.assertFalse(any(c == "git pull --ff-only" for c in called_cmds))
+
+    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
+    def test_ensure_clean_and_synced_no_upstream_skips(self, mock_run) -> None:
+        def fake(cmd: str, *args, **kwargs):
+            class R:
+                def __init__(self, stdout: str = ""):
+                    self.stdout = stdout
+                    self.stderr = ""
+                    self.returncode = 0
+
+            if "git rev-parse --abbrev-ref --symbolic-full-name @{u}" in cmd:
+                return R(stdout="")  # no upstream
+            return R(stdout="")
+
+        mock_run.side_effect = fake
+
+        ensure_clean_and_synced(preview=False)
+
+        called_cmds = [c.args[0] for c in mock_run.call_args_list]
+        self.assertTrue(any("git rev-parse" in c for c in called_cmds))
+        self.assertFalse(any(c == "git fetch --prune --tags" for c in called_cmds))
+        self.assertFalse(any(c == "git pull --ff-only" for c in called_cmds))
+
+    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
+    def test_ensure_clean_and_synced_real_runs_fetch_and_pull(self, mock_run) -> None:
+        mock_run.side_effect = self._fake_run
+
+        ensure_clean_and_synced(preview=False)
+
+        called_cmds = [c.args[0] for c in mock_run.call_args_list]
+        self.assertIn("git fetch origin --prune --tags --force", called_cmds)
+        self.assertIn("git pull --ff-only", called_cmds)
+
+
+
+class TestIsHighestVersionTag(unittest.TestCase):
+    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
+    def test_is_highest_version_tag_no_tags_true(self, mock_run) -> None:
+        def fake(cmd: str, *args, **kwargs):
+            class R:
+                def __init__(self, stdout: str = ""):
+                    self.stdout = stdout
+                    self.stderr = ""
+                    self.returncode = 0
+
+            if "git tag --list" in cmd and "'v*'" in cmd:
+                return R(stdout="")  # no tags
+            return R(stdout="")
+
+        mock_run.side_effect = fake
+
+        self.assertTrue(is_highest_version_tag("v1.0.0"))
+
+        # ensure at least the list command was queried
+        called_cmds = [c.args[0] for c in mock_run.call_args_list]
+        self.assertTrue(any("git tag --list" in c for c in called_cmds))
+
+    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
+    def test_is_highest_version_tag_compares_sort_v(self, mock_run) -> None:
+        """
+        This test is aligned with the CURRENT implementation:
+
+            return tag >= latest
+
+        which is a *string comparison*, not a semantic version compare.
+        Therefore, a candidate like v1.2.0 is lexicographically >= v1.10.0
+        (because '2' > '1' at the first differing char after 'v1.').
+        """
+        def fake(cmd: str, *args, **kwargs):
+            class R:
+                def __init__(self, stdout: str = ""):
+                    self.stdout = stdout
+                    self.stderr = ""
+                    self.returncode = 0
+
+            if cmd.strip() == "git tag --list 'v*'":
+                return R(stdout="v1.0.0\nv1.2.0\nv1.10.0\n")
+            if "git tag --list 'v*'" in cmd and "sort -V" in cmd and "tail -n1" in cmd:
+                return R(stdout="v1.10.0")
+            return R(stdout="")
+
+        mock_run.side_effect = fake
+
+        # With the current implementation (string >=), both of these are True.
+        self.assertTrue(is_highest_version_tag("v1.10.0"))
+        self.assertTrue(is_highest_version_tag("v1.2.0"))
+
+        # And a clearly lexicographically smaller candidate should be False.
+        # Example: "v1.0.0" < "v1.10.0"
+        self.assertFalse(is_highest_version_tag("v1.0.0"))
+
+        # Ensure both capture commands were executed
+        called_cmds = [c.args[0] for c in mock_run.call_args_list]
+        self.assertTrue(any(cmd == "git tag --list 'v*'" for cmd in called_cmds))
+        self.assertTrue(any("sort -V" in cmd and "tail -n1" in cmd for cmd in called_cmds))
 
 
 class TestUpdateLatestTag(unittest.TestCase):
     @patch("pkgmgr.actions.release.git_ops.run_git_command")
-    def test_update_latest_tag_preview_does_not_call_git(
+    def test_update_latest_tag_preview_does_not_call_git(self, mock_run_git_command) -> None:
-        self,
-        mock_run_git_command,
-    ) -> None:
         update_latest_tag("v1.2.3", preview=True)
         mock_run_git_command.assert_not_called()
 
     @patch("pkgmgr.actions.release.git_ops.run_git_command")
-    def test_update_latest_tag_real_calls_git_with_dereference_and_message(
+    def test_update_latest_tag_real_calls_git(self, mock_run_git_command) -> None:
-        self,
-        mock_run_git_command,
-    ) -> None:
         update_latest_tag("v1.2.3", preview=False)
 
         calls = [c.args[0] for c in mock_run_git_command.call_args_list]
-        # Must dereference the tag object and create an annotated tag with message
         self.assertIn(
             'git tag -f -a latest v1.2.3^{} -m "Floating latest tag for v1.2.3"',
             calls,
         )
         self.assertIn("git push origin latest --force", calls)
 
+
 if __name__ == "__main__":
     unittest.main()

tests/unit/pkgmgr/actions/release/test_init.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import unittest
+
+
+class TestReleasePackageInit(unittest.TestCase):
+    def test_release_is_reexported(self) -> None:
+        from pkgmgr.actions.release import release  # noqa: F401
+
+        self.assertTrue(callable(release))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/release/test_prompts.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.actions.release.prompts import (
+    confirm_proceed_release,
+    should_delete_branch,
+)
+
+
+class TestShouldDeleteBranch(unittest.TestCase):
+    def test_force_true_skips_prompt_and_returns_true(self) -> None:
+        self.assertTrue(should_delete_branch(force=True))
+
+    @patch("pkgmgr.actions.release.prompts.sys.stdin.isatty", return_value=False)
+    def test_non_interactive_returns_false(self, _mock_isatty) -> None:
+        self.assertFalse(should_delete_branch(force=False))
+
+    @patch("pkgmgr.actions.release.prompts.sys.stdin.isatty", return_value=True)
+    @patch("builtins.input", return_value="y")
+    def test_interactive_yes_returns_true(self, _mock_input, _mock_isatty) -> None:
+        self.assertTrue(should_delete_branch(force=False))
+
+    @patch("pkgmgr.actions.release.prompts.sys.stdin.isatty", return_value=True)
+    @patch("builtins.input", return_value="N")
+    def test_interactive_no_returns_false(self, _mock_input, _mock_isatty) -> None:
+        self.assertFalse(should_delete_branch(force=False))
+
+
+class TestConfirmProceedRelease(unittest.TestCase):
+    @patch("builtins.input", return_value="y")
+    def test_confirm_yes(self, _mock_input) -> None:
+        self.assertTrue(confirm_proceed_release())
+
+    @patch("builtins.input", return_value="no")
+    def test_confirm_no(self, _mock_input) -> None:
+        self.assertFalse(confirm_proceed_release())
+
+    @patch("builtins.input", side_effect=EOFError)
+    def test_confirm_eof_returns_false(self, _mock_input) -> None:
+        self.assertFalse(confirm_proceed_release())
+
+    @patch("builtins.input", side_effect=KeyboardInterrupt)
+    def test_confirm_keyboard_interrupt_returns_false(self, _mock_input) -> None:
+        self.assertFalse(confirm_proceed_release())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/release/test_release_orchestration.py

@@ -1,155 +0,0 @@
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from pkgmgr.core.version.semver import SemVer
-from pkgmgr.actions.release import release
-
-
-class TestReleaseOrchestration(unittest.TestCase):
-    def test_release_happy_path_uses_helpers_and_git(self) -> None:
-        with patch("pkgmgr.actions.release.sys.stdin.isatty", return_value=False), \
-            patch("pkgmgr.actions.release.determine_current_version") as mock_determine_current_version, \
-            patch("pkgmgr.actions.release.bump_semver") as mock_bump_semver, \
-            patch("pkgmgr.actions.release.update_pyproject_version") as mock_update_pyproject, \
-            patch("pkgmgr.actions.release.update_changelog") as mock_update_changelog, \
-            patch("pkgmgr.actions.release.get_current_branch", return_value="develop") as mock_get_current_branch, \
-            patch("pkgmgr.actions.release.update_flake_version") as mock_update_flake, \
-            patch("pkgmgr.actions.release.update_pkgbuild_version") as mock_update_pkgbuild, \
-            patch("pkgmgr.actions.release.update_spec_version") as mock_update_spec, \
-            patch("pkgmgr.actions.release.update_debian_changelog") as mock_update_debian_changelog, \
-            patch("pkgmgr.actions.release.update_spec_changelog") as mock_update_spec_changelog, \
-            patch("pkgmgr.actions.release.run_git_command") as mock_run_git_command, \
-            patch("pkgmgr.actions.release.sync_branch_with_remote") as mock_sync_branch, \
-            patch("pkgmgr.actions.release.update_latest_tag") as mock_update_latest_tag:
-            mock_determine_current_version.return_value = SemVer(1, 2, 3)
-            mock_bump_semver.return_value = SemVer(1, 2, 4)
-
-            release(
-                pyproject_path="pyproject.toml",
-                changelog_path="CHANGELOG.md",
-                release_type="patch",
-                message="Test release",
-                preview=False,
-            )
-
-            # Current version + bump
-            mock_determine_current_version.assert_called_once()
-            mock_bump_semver.assert_called_once()
-            args, kwargs = mock_bump_semver.call_args
-            self.assertEqual(args[0], SemVer(1, 2, 3))
-            self.assertEqual(args[1], "patch")
-            self.assertEqual(kwargs, {})
-
-            # pyproject update
-            mock_update_pyproject.assert_called_once()
-            args, kwargs = mock_update_pyproject.call_args
-            self.assertEqual(args[0], "pyproject.toml")
-            self.assertEqual(args[1], "1.2.4")
-            self.assertEqual(kwargs.get("preview"), False)
-
-            # changelog update (Projekt)
-            mock_update_changelog.assert_called_once()
-            args, kwargs = mock_update_changelog.call_args
-            self.assertEqual(args[0], "CHANGELOG.md")
-            self.assertEqual(args[1], "1.2.4")
-            self.assertEqual(kwargs.get("message"), "Test release")
-            self.assertEqual(kwargs.get("preview"), False)
-
-            # Additional packaging helpers called with preview=False
-            mock_update_flake.assert_called_once()
-            self.assertEqual(mock_update_flake.call_args[1].get("preview"), False)
-
-            mock_update_pkgbuild.assert_called_once()
-            self.assertEqual(mock_update_pkgbuild.call_args[1].get("preview"), False)
-
-            mock_update_spec.assert_called_once()
-            self.assertEqual(mock_update_spec.call_args[1].get("preview"), False)
-
-            mock_update_debian_changelog.assert_called_once()
-            self.assertEqual(
-                mock_update_debian_changelog.call_args[1].get("preview"),
-                False,
-            )
-
-            # Fedora / RPM %changelog helper
-            mock_update_spec_changelog.assert_called_once()
-            self.assertEqual(
-                mock_update_spec_changelog.call_args[1].get("preview"),
-                False,
-            )
-
-            # Git operations
-            mock_get_current_branch.assert_called_once()
-            self.assertEqual(mock_get_current_branch.return_value, "develop")
-
-            git_calls = [c.args[0] for c in mock_run_git_command.call_args_list]
-            self.assertIn('git commit -am "Release version 1.2.4"', git_calls)
-            self.assertIn('git tag -a v1.2.4 -m "Test release"', git_calls)
-            self.assertIn("git push origin develop", git_calls)
-            self.assertIn("git push origin --tags", git_calls)
-
-            # Branch sync & latest tag update
-            mock_sync_branch.assert_called_once_with("develop", preview=False)
-            mock_update_latest_tag.assert_called_once_with("v1.2.4", preview=False)
-
-    def test_release_preview_mode_skips_git_and_uses_preview_flag(self) -> None:
-        with patch("pkgmgr.actions.release.determine_current_version") as mock_determine_current_version, \
-            patch("pkgmgr.actions.release.bump_semver") as mock_bump_semver, \
-            patch("pkgmgr.actions.release.update_pyproject_version") as mock_update_pyproject, \
-            patch("pkgmgr.actions.release.update_changelog") as mock_update_changelog, \
-            patch("pkgmgr.actions.release.get_current_branch", return_value="develop") as mock_get_current_branch, \
-            patch("pkgmgr.actions.release.update_flake_version") as mock_update_flake, \
-            patch("pkgmgr.actions.release.update_pkgbuild_version") as mock_update_pkgbuild, \
-            patch("pkgmgr.actions.release.update_spec_version") as mock_update_spec, \
-            patch("pkgmgr.actions.release.update_debian_changelog") as mock_update_debian_changelog, \
-            patch("pkgmgr.actions.release.update_spec_changelog") as mock_update_spec_changelog, \
-            patch("pkgmgr.actions.release.run_git_command") as mock_run_git_command, \
-            patch("pkgmgr.actions.release.sync_branch_with_remote") as mock_sync_branch, \
-            patch("pkgmgr.actions.release.update_latest_tag") as mock_update_latest_tag:
-            mock_determine_current_version.return_value = SemVer(1, 2, 3)
-            mock_bump_semver.return_value = SemVer(1, 2, 4)
-
-            release(
-                pyproject_path="pyproject.toml",
-                changelog_path="CHANGELOG.md",
-                release_type="patch",
-                message="Preview release",
-                preview=True,
-            )
-
-            # All update helpers must be called with preview=True
-            mock_update_pyproject.assert_called_once()
-            self.assertTrue(mock_update_pyproject.call_args[1].get("preview"))
-
-            mock_update_changelog.assert_called_once()
-            self.assertTrue(mock_update_changelog.call_args[1].get("preview"))
-
-            mock_update_flake.assert_called_once()
-            self.assertTrue(mock_update_flake.call_args[1].get("preview"))
-
-            mock_update_pkgbuild.assert_called_once()
-            self.assertTrue(mock_update_pkgbuild.call_args[1].get("preview"))
-
-            mock_update_spec.assert_called_once()
-            self.assertTrue(mock_update_spec.call_args[1].get("preview"))
-
-            mock_update_debian_changelog.assert_called_once()
-            self.assertTrue(mock_update_debian_changelog.call_args[1].get("preview"))
-
-            # Fedora / RPM spec changelog helper in preview mode
-            mock_update_spec_changelog.assert_called_once()
-            self.assertTrue(mock_update_spec_changelog.call_args[1].get("preview"))
-
-            # In preview mode no real git commands must be executed
-            mock_run_git_command.assert_not_called()
-
-            # Branch sync is still invoked (with preview=True internally),
-            # and latest tag is only announced in preview mode
-            mock_sync_branch.assert_called_once_with("develop", preview=True)
-            mock_update_latest_tag.assert_called_once_with("v1.2.4", preview=True)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/pkgmgr/actions/release/test_workflow.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.actions.release.workflow import release
+
+
+class TestWorkflowReleaseEntryPoint(unittest.TestCase):
+    @patch("pkgmgr.actions.release.workflow._release_impl")
+    def test_release_preview_calls_impl_preview_only(self, mock_impl) -> None:
+        release(preview=True, force=False, close=False)
+
+        mock_impl.assert_called_once()
+        kwargs = mock_impl.call_args.kwargs
+        self.assertTrue(kwargs["preview"])
+        self.assertFalse(kwargs["force"])
+
+    @patch("pkgmgr.actions.release.workflow._release_impl")
+    @patch("pkgmgr.actions.release.workflow.sys.stdin.isatty", return_value=False)
+    def test_release_non_interactive_runs_real_without_confirmation(self, _mock_isatty, mock_impl) -> None:
+        release(preview=False, force=False, close=False)
+
+        mock_impl.assert_called_once()
+        kwargs = mock_impl.call_args.kwargs
+        self.assertFalse(kwargs["preview"])
+
+    @patch("pkgmgr.actions.release.workflow._release_impl")
+    def test_release_force_runs_real_without_confirmation(self, mock_impl) -> None:
+        release(preview=False, force=True, close=False)
+
+        mock_impl.assert_called_once()
+        kwargs = mock_impl.call_args.kwargs
+        self.assertFalse(kwargs["preview"])
+        self.assertTrue(kwargs["force"])
+
+    @patch("pkgmgr.actions.release.workflow._release_impl")
+    @patch("pkgmgr.actions.release.workflow.confirm_proceed_release", return_value=False)
+    @patch("pkgmgr.actions.release.workflow.sys.stdin.isatty", return_value=True)
+    def test_release_interactive_decline_runs_only_preview(self, _mock_isatty, _mock_confirm, mock_impl) -> None:
+        release(preview=False, force=False, close=False)
+
+        # interactive path: preview first, then decline => only one call
+        self.assertEqual(mock_impl.call_count, 1)
+        self.assertTrue(mock_impl.call_args_list[0].kwargs["preview"])
+
+    @patch("pkgmgr.actions.release.workflow._release_impl")
+    @patch("pkgmgr.actions.release.workflow.confirm_proceed_release", return_value=True)
+    @patch("pkgmgr.actions.release.workflow.sys.stdin.isatty", return_value=True)
+    def test_release_interactive_accept_runs_preview_then_real(self, _mock_isatty, _mock_confirm, mock_impl) -> None:
+        release(preview=False, force=False, close=False)
+
+        self.assertEqual(mock_impl.call_count, 2)
+        self.assertTrue(mock_impl.call_args_list[0].kwargs["preview"])
+        self.assertFalse(mock_impl.call_args_list[1].kwargs["preview"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/test_branch.py

@@ -1,146 +0,0 @@
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from pkgmgr.actions.branch import open_branch
-from pkgmgr.core.git import GitError
-
-
-class TestOpenBranch(unittest.TestCase):
-    @patch("pkgmgr.actions.branch.run_git")
-    def test_open_branch_with_explicit_name_and_default_base(self, mock_run_git) -> None:
-        """
-        open_branch(name, base='main') should:
-        - resolve base branch (prefers 'main', falls back to 'master')
-        - fetch origin
-        - checkout resolved base
-        - pull resolved base
-        - create new branch
-        - push with upstream
-        """
-        mock_run_git.return_value = ""
-
-        open_branch(name="feature/test", base_branch="main", cwd="/repo")
-
-        # We expect a specific sequence of Git calls.
-        expected_calls = [
-            (["rev-parse", "--verify", "main"], "/repo"),
-            (["fetch", "origin"], "/repo"),
-            (["checkout", "main"], "/repo"),
-            (["pull", "origin", "main"], "/repo"),
-            (["checkout", "-b", "feature/test"], "/repo"),
-            (["push", "-u", "origin", "feature/test"], "/repo"),
-        ]
-
-        self.assertEqual(mock_run_git.call_count, len(expected_calls))
-
-        for call, (args_expected, cwd_expected) in zip(
-            mock_run_git.call_args_list, expected_calls
-        ):
-            args, kwargs = call
-            self.assertEqual(args[0], args_expected)
-            self.assertEqual(kwargs.get("cwd"), cwd_expected)
-
-    @patch("builtins.input", return_value="feature/interactive")
-    @patch("pkgmgr.actions.branch.run_git")
-    def test_open_branch_prompts_for_name_if_missing(
-        self,
-        mock_run_git,
-        mock_input,
-    ) -> None:
-        """
-        If name is None/empty, open_branch should prompt via input()
-        and still perform the full Git sequence on the resolved base.
-        """
-        mock_run_git.return_value = ""
-
-        open_branch(name=None, base_branch="develop", cwd="/repo")
-
-        # Ensure we asked for input exactly once
-        mock_input.assert_called_once()
-
-        expected_calls = [
-            (["rev-parse", "--verify", "develop"], "/repo"),
-            (["fetch", "origin"], "/repo"),
-            (["checkout", "develop"], "/repo"),
-            (["pull", "origin", "develop"], "/repo"),
-            (["checkout", "-b", "feature/interactive"], "/repo"),
-            (["push", "-u", "origin", "feature/interactive"], "/repo"),
-        ]
-
-        self.assertEqual(mock_run_git.call_count, len(expected_calls))
-        for call, (args_expected, cwd_expected) in zip(
-            mock_run_git.call_args_list, expected_calls
-        ):
-            args, kwargs = call
-            self.assertEqual(args[0], args_expected)
-            self.assertEqual(kwargs.get("cwd"), cwd_expected)
-
-    @patch("pkgmgr.actions.branch.run_git")
-    def test_open_branch_raises_runtimeerror_on_fetch_failure(self, mock_run_git) -> None:
-        """
-        If a GitError occurs on fetch, open_branch should raise a RuntimeError
-        with a helpful message.
-        """
-
-        def side_effect(args, cwd="."):
-            # First call: base resolution (rev-parse) should succeed
-            if args == ["rev-parse", "--verify", "main"]:
-                return ""
-            # Second call: fetch should fail
-            if args == ["fetch", "origin"]:
-                raise GitError("simulated fetch failure")
-            return ""
-
-        mock_run_git.side_effect = side_effect
-
-        with self.assertRaises(RuntimeError) as cm:
-            open_branch(name="feature/fail", base_branch="main", cwd="/repo")
-
-        msg = str(cm.exception)
-        self.assertIn("Failed to fetch from origin", msg)
-        self.assertIn("simulated fetch failure", msg)
-
-    @patch("pkgmgr.actions.branch.run_git")
-    def test_open_branch_uses_fallback_master_if_main_missing(self, mock_run_git) -> None:
-        """
-        If the preferred base (e.g. 'main') does not exist, open_branch should
-        fall back to the fallback base (default: 'master').
-        """
-
-        def side_effect(args, cwd="."):
-            # First: rev-parse main -> fails
-            if args == ["rev-parse", "--verify", "main"]:
-                raise GitError("main does not exist")
-            # Second: rev-parse master -> succeeds
-            if args == ["rev-parse", "--verify", "master"]:
-                return ""
-            # Then normal flow on master
-            return ""
-
-        mock_run_git.side_effect = side_effect
-
-        open_branch(name="feature/fallback", base_branch="main", cwd="/repo")
-
-        expected_calls = [
-            (["rev-parse", "--verify", "main"], "/repo"),
-            (["rev-parse", "--verify", "master"], "/repo"),
-            (["fetch", "origin"], "/repo"),
-            (["checkout", "master"], "/repo"),
-            (["pull", "origin", "master"], "/repo"),
-            (["checkout", "-b", "feature/fallback"], "/repo"),
-            (["push", "-u", "origin", "feature/fallback"], "/repo"),
-        ]
-
-        self.assertEqual(mock_run_git.call_count, len(expected_calls))
-        for call, (args_expected, cwd_expected) in zip(
-            mock_run_git.call_args_list, expected_calls
-        ):
-            args, kwargs = call
-            self.assertEqual(args[0], args_expected)
-            self.assertEqual(kwargs.get("cwd"), cwd_expected)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/pkgmgr/cli/test_branch_cli.py

@@ -1,112 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Unit tests for the `pkgmgr branch` CLI wiring.
-
-These tests verify that:
-  - The argument parser creates the correct structure for
-    `branch open` and `branch close`.
-  - `handle_branch` calls the corresponding helper functions
-    with the expected arguments (including base branch and cwd).
-"""
-
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from pkgmgr.cli.parser import create_parser
-from pkgmgr.cli.commands.branch import handle_branch
-
-
-class TestBranchCLI(unittest.TestCase):
-    """
-    Tests for the branch subcommands implemented in cli.
-    """
-
-    def _create_parser(self):
-        """
-        Create the top-level parser with a minimal description.
-        """
-        return create_parser("pkgmgr test parser")
-
-    @patch("pkgmgr.cli.commands.branch.open_branch")
-    def test_branch_open_with_name_and_base(self, mock_open_branch):
-        """
-        Ensure that `pkgmgr branch open <name> --base <branch>` calls
-        open_branch() with the correct parameters.
-        """
-        parser = self._create_parser()
-        args = parser.parse_args(
-            ["branch", "open", "feature/test-branch", "--base", "develop"]
-        )
-
-        # Sanity check: parser wiring
-        self.assertEqual(args.command, "branch")
-        self.assertEqual(args.subcommand, "open")
-        self.assertEqual(args.name, "feature/test-branch")
-        self.assertEqual(args.base, "develop")
-
-        # ctx is currently unused by handle_branch, so we can pass None
-        handle_branch(args, ctx=None)
-
-        mock_open_branch.assert_called_once()
-        _args, kwargs = mock_open_branch.call_args
-
-        self.assertEqual(kwargs.get("name"), "feature/test-branch")
-        self.assertEqual(kwargs.get("base_branch"), "develop")
-        self.assertEqual(kwargs.get("cwd"), ".")
-
-    @patch("pkgmgr.cli.commands.branch.close_branch")
-    def test_branch_close_with_name_and_base(self, mock_close_branch):
-        """
-        Ensure that `pkgmgr branch close <name> --base <branch>` calls
-        close_branch() with the correct parameters.
-        """
-        parser = self._create_parser()
-        args = parser.parse_args(
-            ["branch", "close", "feature/old-branch", "--base", "main"]
-        )
-
-        # Sanity check: parser wiring
-        self.assertEqual(args.command, "branch")
-        self.assertEqual(args.subcommand, "close")
-        self.assertEqual(args.name, "feature/old-branch")
-        self.assertEqual(args.base, "main")
-
-        handle_branch(args, ctx=None)
-
-        mock_close_branch.assert_called_once()
-        _args, kwargs = mock_close_branch.call_args
-
-        self.assertEqual(kwargs.get("name"), "feature/old-branch")
-        self.assertEqual(kwargs.get("base_branch"), "main")
-        self.assertEqual(kwargs.get("cwd"), ".")
-
-    @patch("pkgmgr.cli.commands.branch.close_branch")
-    def test_branch_close_without_name_uses_none(self, mock_close_branch):
-        """
-        Ensure that `pkgmgr branch close` without a name passes name=None
-        into close_branch(), leaving branch resolution to the helper.
-        """
-        parser = self._create_parser()
-        args = parser.parse_args(["branch", "close"])
-
-        # Parser wiring: no name → None
-        self.assertEqual(args.command, "branch")
-        self.assertEqual(args.subcommand, "close")
-        self.assertIsNone(args.name)
-
-        handle_branch(args, ctx=None)
-
-        mock_close_branch.assert_called_once()
-        _args, kwargs = mock_close_branch.call_args
-
-        self.assertIsNone(kwargs.get("name"))
-        self.assertEqual(kwargs.get("base_branch"), "main")
-        self.assertEqual(kwargs.get("cwd"), ".")
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/pkgmgr/cli/test_handle_branch.py

@@ -22,6 +22,10 @@ class TestCliBranch(unittest.TestCase):
             user_config_path="/tmp/config.yaml",
         )
 
+    # ------------------------------------------------------------------
+    # open subcommand
+    # ------------------------------------------------------------------
+
     @patch("pkgmgr.cli.commands.branch.open_branch")
     def test_handle_branch_open_forwards_args_to_open_branch(self, mock_open_branch) -> None:
         """
@@ -73,13 +77,15 @@ class TestCliBranch(unittest.TestCase):
     @patch("pkgmgr.cli.commands.branch.close_branch")
     def test_handle_branch_close_forwards_args_to_close_branch(self, mock_close_branch) -> None:
         """
-        handle_branch('close') should call close_branch with name, base and cwd='.'.
+        handle_branch('close') should call close_branch with name, base,
+        cwd='.' and force=False by default.
         """
         args = SimpleNamespace(
             command="branch",
             subcommand="close",
             name="feature/cli-close",
             base="develop",
+            force=False,
         )
 
         ctx = self._dummy_ctx()
@@ -91,6 +97,7 @@ class TestCliBranch(unittest.TestCase):
         self.assertEqual(call_kwargs.get("name"), "feature/cli-close")
         self.assertEqual(call_kwargs.get("base_branch"), "develop")
         self.assertEqual(call_kwargs.get("cwd"), ".")
+        self.assertFalse(call_kwargs.get("force"))
 
     @patch("pkgmgr.cli.commands.branch.close_branch")
     def test_handle_branch_close_uses_default_base_when_not_set(self, mock_close_branch) -> None:
@@ -103,6 +110,7 @@ class TestCliBranch(unittest.TestCase):
             subcommand="close",
             name=None,
             base="main",
+            force=False,
         )
 
         ctx = self._dummy_ctx()
@@ -114,6 +122,113 @@ class TestCliBranch(unittest.TestCase):
         self.assertIsNone(call_kwargs.get("name"))
         self.assertEqual(call_kwargs.get("base_branch"), "main")
         self.assertEqual(call_kwargs.get("cwd"), ".")
+        self.assertFalse(call_kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.close_branch")
+    def test_handle_branch_close_with_force_true(self, mock_close_branch) -> None:
+        """
+        handle_branch('close') should pass force=True when the args specify it.
+        """
+        args = SimpleNamespace(
+            command="branch",
+            subcommand="close",
+            name="feature/cli-close-force",
+            base="main",
+            force=True,
+        )
+
+        ctx = self._dummy_ctx()
+
+        handle_branch(args, ctx)
+
+        mock_close_branch.assert_called_once()
+        _, call_kwargs = mock_close_branch.call_args
+        self.assertEqual(call_kwargs.get("name"), "feature/cli-close-force")
+        self.assertEqual(call_kwargs.get("base_branch"), "main")
+        self.assertEqual(call_kwargs.get("cwd"), ".")
+        self.assertTrue(call_kwargs.get("force"))
+
+    # ------------------------------------------------------------------
+    # drop subcommand
+    # ------------------------------------------------------------------
+
+    @patch("pkgmgr.cli.commands.branch.drop_branch")
+    def test_handle_branch_drop_forwards_args_to_drop_branch(self, mock_drop_branch) -> None:
+        """
+        handle_branch('drop') should call drop_branch with name, base,
+        cwd='.' and force=False by default.
+        """
+        args = SimpleNamespace(
+            command="branch",
+            subcommand="drop",
+            name="feature/cli-drop",
+            base="develop",
+            force=False,
+        )
+
+        ctx = self._dummy_ctx()
+
+        handle_branch(args, ctx)
+
+        mock_drop_branch.assert_called_once()
+        _, call_kwargs = mock_drop_branch.call_args
+        self.assertEqual(call_kwargs.get("name"), "feature/cli-drop")
+        self.assertEqual(call_kwargs.get("base_branch"), "develop")
+        self.assertEqual(call_kwargs.get("cwd"), ".")
+        self.assertFalse(call_kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.drop_branch")
+    def test_handle_branch_drop_uses_default_base_when_not_set(self, mock_drop_branch) -> None:
+        """
+        If --base is not passed for 'drop', argparse gives base='main'
+        (default), and handle_branch should propagate that to drop_branch.
+        """
+        args = SimpleNamespace(
+            command="branch",
+            subcommand="drop",
+            name=None,
+            base="main",
+            force=False,
+        )
+
+        ctx = self._dummy_ctx()
+
+        handle_branch(args, ctx)
+
+        mock_drop_branch.assert_called_once()
+        _, call_kwargs = mock_drop_branch.call_args
+        self.assertIsNone(call_kwargs.get("name"))
+        self.assertEqual(call_kwargs.get("base_branch"), "main")
+        self.assertEqual(call_kwargs.get("cwd"), ".")
+        self.assertFalse(call_kwargs.get("force"))
+
+    @patch("pkgmgr.cli.commands.branch.drop_branch")
+    def test_handle_branch_drop_with_force_true(self, mock_drop_branch) -> None:
+        """
+        handle_branch('drop') should pass force=True when the args specify it.
+        """
+        args = SimpleNamespace(
+            command="branch",
+            subcommand="drop",
+            name="feature/cli-drop-force",
+            base="main",
+            force=True,
+        )
+
+        ctx = self._dummy_ctx()
+
+        handle_branch(args, ctx)
+
+        mock_drop_branch.assert_called_once()
+        _, call_kwargs = mock_drop_branch.call_args
+        self.assertEqual(call_kwargs.get("name"), "feature/cli-drop-force")
+        self.assertEqual(call_kwargs.get("base_branch"), "main")
+        self.assertEqual(call_kwargs.get("cwd"), ".")
+        self.assertTrue(call_kwargs.get("force"))
+
+    # ------------------------------------------------------------------
+    # unknown subcommand
+    # ------------------------------------------------------------------
 
     def test_handle_branch_unknown_subcommand_exits_with_code_2(self) -> None:
         """